taler-docs

commit ca1ac2387e9bace0f0ac159dc49313a57e45a074
parent fd3a52673ceda79d093181a36729330199775670
Author: Martin Schanzenbach <schanzen@gnunet.org>
Date:   Sun, 15 Dec 2024 16:23:29 +0100

Update TalDir spec

Diffstat:
M
core/api-taldir.rst
 | 
41
+++++++++++++++++++++--------------------

1 file changed, 21 insertions(+), 20 deletions(-)
diff --git a/core/api-taldir.rst b/core/api-taldir.rst
@@ -28,6 +28,9 @@ 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 service in principle allows registration of any valid URI as inbox
+service.
+For Taler, the URI must follow the format defined in TODO.
 
 The API specified here follows the :ref:`general conventions <http-common>`
 for all details not specified in the individual requests.
@@ -110,11 +113,8 @@ Address registration
       // Address, in $METHOD-specific format
       address: string;
 
-      // Public key of the user to register. As string in Crockfor base32 encoding.
-      public_key: EddsaPublicKey;
-
-      // (HTTPS) endpoint URL for the inbox service.
-      inbox_url: string;
+      // Target URI to associate with this address.
+      target_uri: string;
 
       // For how long should the registration last/be extended.
       duration: RelativeTime;
@@ -168,10 +168,9 @@ Address registration
     }
 
 
-.. http:get:: /register/$H_ADDRESS/$PINTAN
+.. http:get:: /register/$H_ADDRESS/$PINTAN?address=$ADDRESS
 
-  Endpoint that generates an HTML Web site with a QR code and
-  ``taler://taldir/$H_ADDRESS/$PINTAN-wallet`` link for completing the
+  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
   it was received on a different device than where the wallet is running).
   Does NOT complete the registration, as some providers automatically click on
@@ -179,17 +178,22 @@ Address registration
   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
+  Opening the link will allow the user to do the POST call to this endpoint.
+  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``
+  ``target_uri`` 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.
+  ``$H_ADDRESS`` is the SHA-512 hash of the address to be registered in
+  Crockford base32 encoding.
+  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
+  for verification.
 
 .. http:post:: /$H_ADDRESS
 
@@ -204,9 +208,8 @@ Address registration
 
     interface IdentityConfirmation {
       // 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.
+      // chosen by TalDir concatenated with the ``inbox_uri`` (both strings
+      // are hashed excluding the 0-terminator).
       // The hash is provided as string in Crockford base32 encoding.
       solution: HashCode;
 
@@ -230,9 +233,9 @@ Address lookup
 
 .. http:get:: /$H_ADDRESS
 
-  Lookup the public key (and mailbox service base URL) associated with
+  Lookup the target URI associated with
   an address in the TalDir. Here, ``$H_ADDRESS`` is the SHA-512 hash of
-  a (presumably) registered address in Crockford base32 encoding.
+  a registered address in Crockford base32 encoding.
 
   **Response**
 
@@ -249,10 +252,8 @@ Address lookup
 
     interface MailboxDetailResponse {
 
-      // Registered public key of the user. As string in Crockford base32 encoding.
-      public_key: EddsaPublicKey;
+      // Target URI to associate with this address.
+      target_uri: string;
 
-      // (HTTPS) endpoint URL for the inbox service.
-      inbox_url: string;
 
     }