[taler-docs] branch master updated: -add draft of taldri api

[gnunet]

This is an automated email from the git hooks/post-receive script.

grothoff pushed a commit to branch master
in repository docs.

The following commit(s) were added to refs/heads/master by this push:
     new 556b4d5  -add draft of taldri api
556b4d5 is described below

commit 556b4d5f9e8acb02110049c334782d1a518c628c
Author: Christian Grothoff <christian@grothoff.org>
AuthorDate: Thu Jun 30 21:40:40 2022 +0200

    -add draft of taldri api
---
 core/api-merchant.rst |   2 +-
 core/api-taldir.rst   | 163 ++++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 164 insertions(+), 1 deletion(-)

diff --git a/core/api-merchant.rst b/core/api-merchant.rst
index cadc1aa..4142b04 100644
--- a/core/api-merchant.rst
+++ b/core/api-merchant.rst
@@ -118,7 +118,7 @@ such as the implemented version of the protocol and the 
currency used.
   **Response:**
 
   :http:statuscode:`200 OK`:
-    The exchange accepted all of the coins. The body is a `VersionResponse`.
+    The body is a `VersionResponse`.
 
   .. ts:def:: VersionResponse
 
diff --git a/core/api-taldir.rst b/core/api-taldir.rst
new file mode 100644
index 0000000..1493300
--- /dev/null
+++ b/core/api-taldir.rst
@@ -0,0 +1,163 @@
+
+
+```
+.. http:get:: /config
+
+  Return the protocol version and currency supported by this service.
+
+  **Response:**
+
+  :http:statuscode:`200 OK`:
+    The body is a `VersionResponse`.
+
+  .. 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-directory";
+
+      // Supported registration methods
+      methods: Method;
+
+      // fee for one month of registration
+      monthly_fee: Amount;
+
+    }
+
+    interface Method {
+      // Name of the method, e.g. "email" or "sms".
+      name: string;
+
+      // per challenge fee
+      challenge_fee: Amount;
+
+    }
+```
+```
+.. 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".
+
+  **Request**
+
+  .. ts:def:: IdentityMessage {
+    // Address, in $METHOD-specific format
+    address: string;
+
+    // Public key of the user to register
+    public_key: EdDSAPublicKey;
+
+    // (HTTPS) endpoint URL for the inbox service.
+    inbox_url: string;
+
+    // For how long should the registration last.
+    duration: Time;
+
+    // Order ID, if the client recently paid for this registration
+    order_id?: string;
+  }
+
+  **Response**
+
+  :http:statuscode:`200 Ok`
+     Registration already exists for this address for the specified duration.
+     Returns for how long this registration is paid for.
+  :http:statuscode:`202 Accepted`
+     Registration was initiated, the client should check for receiving
+     a challenge at the address where registration was attempted.
+  :http:statuscode:`402 Payment Required`
+     Client needs to make a Taler payment before proceeding. See
+     standard Taler payment procedure.
+  :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`_.
+
+  .. _RateLimitedMessage:
+  .. ts:def:: RateLimitedMessage
+
+    interface RateLimitedMessage {
+
+      // Taler error code, TALER_EC_TALDIR_REGISTER_RATE_LIMITED.
+      code: number;
+
+      // At what frequency are new registrations allowed.
+      request_frequency: RelativeTime;
+
+      // The human readable error message.
+      hint: string;
+
+    }
+
+
+```
+```
+.. 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.
+
+.. http:post:: /$H_ADDRESS
+
+  Where $ID_KEY is the SHA-512 hash of the to be registered address in 
Crockford base32 encoding.
+
+  **Request**
+
+  .. ts:def:: IdentityConfirmation {
+    // The challenge ($PINTAN) value chosen by TalDir hashed
+    // with the wallet's public key.
+    solution: Hash;
+
+  }
+
+  **Response**
+
+  :http:statuscode:`204 No Content`:
+     Registration complete.
+  :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).
+  :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.
+
+.. http:get:: /$H_ADDRESS
+
+  **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`
+  :http:statuscode:`404 Not found`:
+     The address is unknown (original registration attempt may have expired).
+
+
+  .. ts:def:: IdentityKey {
+
+    // Registered public key of the user
+    public_key: EdDSAPublicKey;
+
+    // (HTTPS) endpoint URL for the inbox service.
+    inbox_url: string;
+
+  }

-- 
To stop receiving notification emails like this one, please contact
gnunet@gnunet.org.