sketch new truth REST API C client

1 files changed, 306 insertions, 3 deletions

diff --git a/src/include/anastasis_service.h b/src/include/anastasis_service.h
index 3bc8f87..dc0fb12 100644
--- a/src/include/anastasis_service.h
+++ b/src/include/anastasis_service.h
@@ -1,6 +1,6 @@
 /*
   This file is part of Anastasis
-  Copyright (C) 2019-2021 Anastasis SARL
+  Copyright (C) 2019-2022 Anastasis SARL
 
   Anastasis is free software; you can redistribute it and/or modify it under the
   terms of the GNU General Public License as published by the Free Software
@@ -462,8 +462,7 @@ struct ANASTASIS_UploadDetails
  * Callback to process a POST /policy request
  *
  * @param cls closure
- * @param http_status HTTP status code for this request
- * @param obj the decoded response body
+ * @param up the decoded response body
  */
 typedef void
 (*ANASTASIS_PolicyStoreCallback) (void *cls,
@@ -830,4 +829,308 @@ ANASTASIS_truth_store_cancel (
   struct ANASTASIS_TruthStoreOperation *tso);
 
 
+/**
+ * Possible ways how to proceed with a challenge.
+ */
+enum ANASTASIS_ChallengeDetailType
+{
+
+  /**
+   * A challenge TAN was sent to the customer.
+   * A hint may be provided as to the address used.
+   */
+  ANASTASIS_CS_TAN_SENT,
+
+  /**
+   * The customer should wire funds to the bank
+   * account address provided.
+   */
+  ANASTASIS_CS_WIRE_FUNDS
+
+};
+
+
+/**
+ * Information returned for a POST /truth/$TID/challenge request.
+ */
+struct ANASTASIS_TruthChallengeDetails
+{
+  /**
+   * HTTP status returned by the server.
+   */
+  unsigned int http_status;
+
+  /**
+   * Taler-specific error code, #TALER_EC_NONE on success.
+   */
+  enum TALER_ErrorCode ec;
+
+  /**
+   * Details depending on @e http_status.
+   */
+  union
+  {
+
+    /**
+     * Information for @e http_status of #MHD_HTTP_OK.
+     */
+    struct
+    {
+      /**
+       * Meta-state about how the challenge was
+       * initiated and what is to be done next.
+       */
+      enum ANASTASIS_ChallengeDetailType cs;
+
+      /**
+       * Details depending on @e cs.
+       */
+      union
+      {
+
+        /**
+         * If @e cs is #ANASTASIS_CS_TAN_SENT, this
+         * is human-readable information as to where
+         * the TAN was sent.
+         */
+        const char *tan_address_hint;
+
+        /**
+         * If @e cs is #ANASTASIS_CS_WIRE_FUNDS, this
+         * structure contains information about where
+         * to wire the funds to authenticate as well
+         * as a hint as to which bank account to send
+         * the funds from.
+         */
+        struct
+        {
+
+          /**
+           * How much should be sent.
+           */
+          struct TALER_Amount amount;
+
+          /**
+           * payto:// URI with the target account number.
+           */
+          const char *target_payto;
+
+          /**
+           * Human-readable hint about which sender bank
+           * account must be used.
+           */
+          const char *sender_hint;
+
+          // FIXME: more? Wire transfer subject?
+
+        } wire_funds;
+
+      } details;
+
+    } success;
+
+    /**
+     * Information returne if @e http_status is #MHD_HTTP_PAYMENT_REQUIRED
+     */
+    struct
+    {
+      /**
+       * A taler://pay/-URI with a request to pay the annual fee for
+       * the service.  Returned if @e us is #ANASTASIS_US_PAYMENT_REQUIRED.
+       */
+      const char *payment_request;
+
+      /**
+       * The payment secret (aka order ID) extracted from the @e payment_request.
+       */
+      struct ANASTASIS_PaymentSecretP ps;
+    } payment_required;
+
+  } details;
+
+};
+
+
+/**
+ * Handle for a POST /truth/$TID/challenge operation.
+ */
+struct ANASTASIS_TruthChallengeOperation;
+
+
+/**
+ * Callback to process a POST /truth/$TID/challenge response.
+ *
+ * @param cls closure
+ * @param tcd details about the key share
+ */
+typedef void
+(*ANASTASIS_TruthChallengeCallback) (
+  void *cls,
+  const struct ANASTASIS_TruthChallengeDetails *tcd);
+
+
+/**
+ * Makes a POST /truth/$TID/challenge request.
+ *
+ * @param ctx execution context
+ * @param backend_url base URL of the merchant backend
+ * @param truth_uuid identification of the Truth
+ * @param truth_key Key used to Decrypt the Truth on the Server
+ * @param payment_secret secret from the previously done payment NULL to trigger payment
+ * @param cb callback which will work the response gotten from the backend
+ * @param cb_cls closure to pass to the callback
+ * @return handle for this operation, NULL upon errors
+ */
+struct ANASTASIS_TruthChallengeOperation *
+ANASTASIS_truth_challenge (
+  struct GNUNET_CURL_Context *ctx,
+  const char *backend_url,
+  const struct ANASTASIS_CRYPTO_TruthUUIDP *truth_uuid,
+  const struct ANASTASIS_CRYPTO_TruthKeyP *truth_key,
+  const struct ANASTASIS_PaymentSecretP *payment_secret,
+  ANASTASIS_KeyShareLookupCallback cb,
+  void *cb_cls);
+
+
+/**
+ * Cancel a POST /truth/$TID/challenge request.
+ *
+ * @param[in] tco operation to cancel
+ */
+void
+ANASTASIS_truth_challenge_cancel (
+  struct ANASTASIS_TruthChallengeOperation *tco);
+
+
+/**
+ * Information returned for a POST /truth/$TID/solve request.
+ */
+struct ANASTASIS_TruthSolveReply
+{
+
+  /**
+   * HTTP status returned by the server.
+   */
+  unsigned int http_status;
+
+  /**
+   * Taler-specific error code, #TALER_EC_NONE on success.
+   */
+  enum TALER_ErrorCode ec;
+
+  /**
+   * Details depending on @e http_status.
+   */
+  union
+  {
+
+    /**
+     * Information returned if @e http_status is #MHD_HTTP_OK.
+     */
+    struct
+    {
+
+      /**
+       * The encrypted key share.
+       */
+      struct ANASTASIS_CRYPTO_EncryptedKeyShareP eks;
+
+    } success;
+
+    /**
+     * Information returne if @e http_status is #MHD_HTTP_PAYMENT_REQUIRED
+     */
+    struct
+    {
+      /**
+       * A taler://pay/-URI with a request to pay the annual fee for
+       * the service.  Returned if @e us is #ANASTASIS_US_PAYMENT_REQUIRED.
+       */
+      const char *payment_request;
+
+      /**
+       * The payment secret (aka order ID) extracted from the @e payment_request.
+       */
+      struct ANASTASIS_PaymentSecretP ps;
+    } payment_required;
+
+    /**
+     * Information returne if @e http_status is #MHD_HTTP_TOO_MANY_REQUESTS.
+     */
+    struct
+    {
+
+      /**
+       * How many requests are allowed at most per @e request_frequency?
+       */
+      uint32_t request_limit;
+
+      /**
+       * Frequency at which requests are allowed / new challenges are
+       * created.
+       */
+      struct GNUNET_TIME_Relative request_frequency;
+    } too_many_requests;
+
+  } details;
+
+};
+
+
+/**
+ * Handle for a POST /truth/$TID/solve operation.
+ */
+struct ANASTASIS_TruthSolveOperation;
+
+
+/**
+ * Callback to process a POST /truth/$TID/solve response.
+ *
+ * @param cls closure
+ * @param kdd details about the key share
+ */
+typedef void
+(*ANASTASIS_TruthSolveCallback) (
+  void *cls,
+  const struct ANASTASIS_TruthSolveReply *trs);
+
+
+/**
+ * Makes a POST /truth/$TID/solve request.
+ *
+ * @param ctx execution context
+ * @param backend_url base URL of the merchant backend
+ * @param truth_uuid identification of the Truth
+ * @param truth_key Key used to Decrypt the Truth on the Server
+ * @param payment_secret secret from the previously done payment NULL to trigger payment
+ * @param timeout how long to wait for the payment, use
+ *           #GNUNET_TIME_UNIT_ZERO to let the server pick
+ * @param hashed_answer hashed answer to the challenge
+ * @param cb callback which will work the response gotten from the backend
+ * @param cb_cls closure to pass to the callback
+ * @return handle for this operation, NULL upon errors
+ */
+struct ANASTASIS_TruthSolveOperation *
+ANASTASIS_truth_solve (
+  struct GNUNET_CURL_Context *ctx,
+  const char *backend_url,
+  const struct ANASTASIS_CRYPTO_TruthUUIDP *truth_uuid,
+  const struct ANASTASIS_CRYPTO_TruthKeyP *truth_key,
+  const struct ANASTASIS_PaymentSecretP *payment_secret,
+  struct GNUNET_TIME_Relative timeout,
+  const struct GNUNET_HashCode *hashed_answer,
+  ANASTASIS_KeyShareLookupCallback cb,
+  void *cb_cls);
+
+
+/**
+ * Cancel a POST /truth/$TID/solve request.
+ *
+ * @param[in] tso handle of the operation to cancel
+ */
+void
+ANASTASIS_truth_solve_cancel (
+  struct ANASTASIS_TruthSolveOperation *tso);
+
+
 #endif  /* _ANASTASIS_SERVICE_H */