commit bf1c6682e4787f6234eda22298ac179fb28d695b
parent 958abf08f382c6369e82e1d174704a5bf7d396ff
Author: Martin Schanzenbach <schanzen@gnunet.org>
Date: Wed, 15 Oct 2025 22:00:10 +0200
taldir: rename address to alias
Diffstat:
| M | core/api-taldir.rst | | | 76 | ++++++++++++++++++++++++++++++++++++++-------------------------------------- |
1 file changed, 38 insertions(+), 38 deletions(-)
diff --git a/core/api-taldir.rst b/core/api-taldir.rst
@@ -23,12 +23,12 @@ Directory RESTful API
=====================
This is the API for the Taler Directory (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
+securely associate an inbox service (URL and public key) with the alias of a
+ 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.
+alias. Examples for aliases include E-mail and phone numbers but also
+social handles.
The service in principle allows registration of any valid URI as inbox
service.
For Taler, the URI is a link to a :ref:`mailbox <api-mailbox>`.
@@ -87,15 +87,15 @@ Configuration information
}
---------------------
-Address registration
---------------------
+------------------
+Alias registration
+------------------
-.. http:post:: /register/$METHOD
+.. http:post:: /register/$ALIASTYPE
- Endpoint to register, extend or modify the registration for an address in
+ Endpoint to register, extend or modify the registration for an alias in
the directory.
- Here, $METHOD is the type of address to register, e.g. "email", or "phone".
+ Here, $ALIASTYPE is the type of alias to register, e.g. "email", or "phone".
Supported methods are listed in the VersionResponse.
Note that duration should be given as a multiple of a month in microseconds.
If the duration is not a multiple of a month it will be rounded to the
@@ -114,10 +114,10 @@ Address registration
.. ts:def:: IdentityMessage
interface IdentityMessage {
- // Address, in $METHOD-specific format
- address: string;
+ // Alias, in $ALIASTYPE-specific format
+ alias: string;
- // Target URI to associate with this address.
+ // Target URI to associate with this alias.
target_uri: string;
// For how long should the registration last/be extended.
@@ -128,12 +128,12 @@ Address registration
**Response**
:http:statuscode:`200 Ok`
- Registration already exists for this address for the specified duration.
+ Registration already exists for this alias for the specified duration.
Returns for how long this registration is paid for.
The response format is given by `AlreadyPaidResponse`_.
:http:statuscode:`202 Accepted`
Registration was initiated, the client should check for receiving
- a challenge at the address where registration was attempted.
+ a challenge at the alias where registration was attempted.
:http:statuscode:`402 Payment Required`
Client needs to make a Taler payment before proceeding. See
standard Taler payment procedure.
@@ -142,7 +142,7 @@ Address registration
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.
+ a challenge for this alias in the given timeframe.
The response format is given by `RateLimitedResponse`_.
.. _RateLimitedResponse:
@@ -172,7 +172,7 @@ Address registration
}
-.. http:get:: /register/$H_ADDRESS/$PINTAN?address=$ADDRESS
+.. http:get:: /register/$H_ALIAS/$PINTAN?alias=$ALIAS
Endpoint that generates an HTML Web site with a link for completing the
registration. Useful to open the registration challenge in a browser (say if
@@ -193,20 +193,20 @@ Address registration
a concurrent registration of a different public key, and the user might
accidentally authorize the registration of the public key of a different
wallet.
- ``$H_ADDRESS`` is the SHA-512 hash of a prefix-free encoding of the
- address to be registered in Crockford Base32 encoding, specifically:
- ``SHA-512(len($METHOD)+len($ADDRESS)||$METHOD||$ADDRESS)``
- The service verifies that ``$ADDRESS`` is, in fact, the preimage of ``$H_ADDRESS``
- and ``$ADDRESS`` as well as the ``inbox_uri`` are displayed to the user
+ ``$H_ALIAS`` is the SHA-512 hash of a prefix-free encoding of the
+ alias to be registered in Crockford Base32 encoding, specifically:
+ ``SHA-512(len($ALIASTYPE)+len($ALIAS)||$ALIASTYPE||$ALIAS)``
+ The service verifies that ``$ALIAS`` is, in fact, the preimage of ``$H_ALIAS``
+ and ``$ALIAS`` as well as the ``inbox_uri`` are displayed to the user
for verification.
-.. http:post:: /$H_ADDRESS
+.. http:post:: /$H_ALIAS
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 a prefix-free encoding of the
- address to be registered in Crockford Base32 encoding.
+ the user of the wallet is indeed able to receive messages for the specified
+ alias.
+ ``$H_ALIAS`` is the SHA-512 hash of a prefix-free encoding of the
+ alias to be registered in Crockford Base32 encoding.
**Request**
@@ -228,21 +228,21 @@ Address registration
:http:statuscode:`403 Forbidden`:
The ``solution`` is invalid. Retrying immediately is allowed.
:http:statuscode:`404 Not found`:
- The address is unknown (original registration attempt may have expired).
+ The alias 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.
+ a challenge for this alias in the given timeframe.
---------------
-Address lookup
---------------
+------------
+Alias lookup
+------------
-.. http:get:: /$H_ADDRESS
+.. http:get:: /$H_ALIAS
Lookup the target URI associated with
- an address in the TalDir. Here,
- ``$H_ADDRESS`` is the SHA-512 hash of a prefix-free encoding of the
- address to be registered in Crockford base32 encoding.
+ an alias in the TalDir. Here,
+ ``$H_ALIAS`` is the SHA-512 hash of a prefix-free encoding of the
+ alias to be registered in Crockford base32 encoding.
**Response**
@@ -252,14 +252,14 @@ Address lookup
:http:statuscode:`200 Ok`:
Registration information returned, of type `MailboxDetailResponse`
:http:statuscode:`404 Not found`:
- The address is unknown (original registration may have expired).
+ The alias is unknown (original registration may have expired).
.. _MailboxDetailResponse:
.. ts:def:: MailboxDetailResponse
interface MailboxDetailResponse {
- // Target URI to associate with this address.
+ // Target URI to associate with this alias.
target_uri: string;
