-very basic skeleton for KYC API

src/exchange/taler-exchange-httpd.h

@@ -1,6 +1,6 @@
 /*
   This file is part of TALER
-  Copyright (C) 2014, 2015, 2020 Taler Systems SA
+  Copyright (C) 2014-2022 Taler Systems SA
 
   TALER is free software; you can redistribute it and/or modify it under the
   terms of the GNU Affero General Public License as published by the Free Software
@@ -26,10 +26,15 @@
 #include <microhttpd.h>
 #include "taler_json_lib.h"
 #include "taler_crypto_lib.h"
+#include "taler_kyclogic_plugin.h"
 #include "taler_extensions.h"
 #include <gnunet/gnunet_mhd_compat.h>
 
 
+/* ************* NOTE: OLD KYC logic,***********
+   new logic is in taler-exchange-httpd_kyc.h!
+   ********************************************* */
+
 /**
  * Enumeration for our KYC modes.
  */

src/exchange/taler-exchange-httpd_kyc.c

@@ -0,0 +1,250 @@
+/*
+  This file is part of TALER
+  Copyright (C) 2022 Taler Systems SA
+
+  TALER is free software; you can redistribute it and/or modify it under the
+  terms of the GNU Affero General Public License as published by the Free Software
+  Foundation; either version 3, or (at your option) any later version.
+
+  TALER is distributed in the hope that it will be useful, but WITHOUT ANY
+  WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
+  A PARTICULAR PURPOSE.  See the GNU Affero General Public License for more details.
+
+  You should have received a copy of the GNU Affero General Public License along with
+  TALER; see the file COPYING.  If not, see <http://www.gnu.org/licenses/>
+*/
+/**
+ * @file taler-exchange-httpd_kyc.c
+ * @brief KYC API for the exchange
+ * @author Christian Grothoff
+ */
+#include "platform.h"
+#include "taler-exchange-httpd_kyc.h"
+
+/**
+ * Information about a KYC provider.
+ */
+struct TEH_KycProvider;
+
+
+/**
+ * Abstract representation of a KYC check.
+ */
+struct TEH_KycCheck
+{
+  /**
+   * Human-readable name given to the KYC check.
+   */
+  char *name;
+
+  /**
+   * Array of @e num_providers providers that offer this type of KYC check.
+   */
+  struct TEH_KycProvider *providers;
+
+  /**
+   * Length of the @e providers array.
+   */
+  unsigned int num_providers;
+
+};
+
+
+struct TEH_KycProvider
+{
+  /**
+   * Name of the provider (configuration section name).
+   */
+  const char *provider_section_name;
+
+  /**
+   * Array of @e num_checks checks performed by this provider.
+   */
+  struct TEH_KycCheck *provided_checks;
+
+  /**
+   * Logic to run for this provider.
+   */
+  struct TEH_KYCLOGIC_Plugin *logic;
+
+  /**
+   * @e provider_section_name specific details to
+   * pass to the @e logic functions.
+   */
+  struct TEH_KYCLOGIC_ProviderDetails *pd;
+
+  /**
+   * Length of the @e checks array.
+   */
+  unsigned int num_checks;
+
+  /**
+   * Type of user this provider supports.
+   */
+  enum TEH_KycUserType user_type;
+};
+
+
+/**
+ * Condition that triggers a need to perform KYC.
+ */
+struct TEH_KycTrigger
+{
+
+  /**
+   * Timeframe to consider for computing the amount
+   * to compare against the @e limit.  Zero for the
+   * wallet balance trigger (as not applicable).
+   */
+  struct GNUNET_TIME_Relative timeframe;
+
+  /**
+   * Maximum amount that can be transacted until
+   * the rule triggers.
+   */
+  struct TALER_Amount limit;
+
+  /**
+   * Array of @e num_checks checks to apply on this trigger.
+   */
+  struct TEH_KycCheck *required_checks;
+
+  /**
+   * Length of the @e checks array.
+   */
+  unsigned int num_checks;
+
+  /**
+   * What event is this trigger for?
+   */
+  enum TEH_KycTriggerEvent trigger;
+
+};
+
+
+/**
+ * Array of @e num_kyc_logics KYC logic plugins we have loaded.
+ */
+static struct TEH_KYCLOGIC_Plugin *kyc_logics;
+
+/**
+ * Length of the #kyc_logics array.
+ */
+static unsigned in num_kyc_logics;
+
+/**
+ * Array of @e num_kyc_checks known types of
+ * KYC checks.
+ */
+static struct TEH_KycCheck *kyc_checks;
+
+/**
+ * Length of the #kyc_checks array.
+ */
+static unsigned int num_kyc_checks;
+
+/**
+ * Array of configured triggers.
+ */
+static struct TEH_KycTrigger *kyc_triggers;
+
+/**
+ * Length of the #kyc_triggers array.
+ */
+static unsigned int num_kyc_triggers;
+
+/**
+ * Array of configured providers.
+ */
+static struct TEH_KycProviders *kyc_providers;
+
+/**
+ * Length of the #kyc_providers array.
+ */
+static unsigned int num_kyc_providers;
+
+
+enum GNUNET_GenericReturnValue
+TEH_kyc_trigger_from_string (const char *trigger_s,
+                             enum TEH_KycTriggerEvent *trigger)
+{
+  GNUNET_break (0);
+  return GNUNET_SYSERR;
+}
+
+
+const char *
+TEH_kyc_trigger2s (enum TEH_KycTriggerEvent trigger)
+{
+  GNUNET_break (0);
+  return NULL;
+}
+
+
+enum GNUNET_GenericReturnValue
+TEH_kyc_user_type_from_string (const char *ut_s,
+                               enum TEH_KycUserType *ut)
+{
+  GNUNET_break (0);
+  return GNUNET_SYSERR;
+}
+
+
+const char *
+TEH_kyc_user_type2s (enum TEH_KycUserType ut)
+{
+  GNUNET_break (0);
+  return NULL;
+}
+
+
+enum GNUNET_GenericReturnValue
+TEH_kyc_init (void)
+{
+  GNUNET_break (0);
+  // iterate over configuration sections,
+  // initialize arrays above
+  // sanity check: ensure at least one provider exists
+  // for any trigger and indidivual or business.
+
+  return GNUNET_OK;
+}
+
+
+void
+TEH_kyc_done (void)
+{
+  // unload plugins
+  // free arrays
+}
+
+
+const char *
+TEH_kyc_test_required (enum TEH_KycTriggerEvent event,
+                       const struct TALER_PaytoHashP *h_payto,
+                       TEH_KycAmountIterator ai,
+                       void *cls)
+{
+  // Check if event(s) may at all require KYC.
+  // If so, check what provider checks are
+  // already satisified for h_payto (with database)
+  // If unsatisfied checks are left, use 'ai'
+  // to check if amount is high enough to trigger them.
+  // If it is, find cheapest provider that satisfies
+  // all of them (or, if multiple providers would be
+  // needed, return one of them).
+  GNUNET_break (0);
+  return NULL;
+}
+
+
+enum GNUNET_GenericReturnValue
+TEH_kyc_get_logic (const char *provider_section_name,
+                   struct TEH_KYCLOGIC_Plugin **plugin,
+                   struct TEH_KYCLOGIC_ProviderDetails **pd)
+{
+  // lookup provider by section name in array,
+  // return internal plugin/pd fields.
+  GNUNET_break (0);
+  return GNUNET_SYSERR;
+}

src/exchange/taler-exchange-httpd_kyc.h

@@ -0,0 +1,220 @@
+/*
+  This file is part of TALER
+  Copyright (C) 2022 Taler Systems SA
+
+  TALER is free software; you can redistribute it and/or modify it under the
+  terms of the GNU Affero General Public License as published by the Free Software
+  Foundation; either version 3, or (at your option) any later version.
+
+  TALER is distributed in the hope that it will be useful, but WITHOUT ANY
+  WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
+  A PARTICULAR PURPOSE.  See the GNU Affero General Public License for more details.
+
+  You should have received a copy of the GNU Affero General Public License along with
+  TALER; see the file COPYING.  If not, see <http://www.gnu.org/licenses/>
+*/
+/**
+ * @file taler-exchange-httpd_kyc.h
+ * @brief KYC API for the exchange
+ * @author Christian Grothoff
+ */
+#ifndef TALER_EXCHANGE_HTTPD_KYC_H
+#define TALER_EXCHANGE_HTTPD_KYC_H
+
+#include <microhttpd.h>
+#include "taler_kyclogic_plugin.h"
+
+
+/**
+ * Enumeration for our KYC user types.
+ */
+enum TEH_KycUserType
+{
+  /**
+   * KYC rule is for an individual.
+   */
+  TEH_KYC_INDIVIDUAL = 0,
+
+  /**
+   * KYC rule is for a business.
+   */
+  TEH_KYC_BUSINESS = 1
+};
+
+
+/**
+ * Enumeration of possible events that may trigger
+ * KYC requirements.
+ */
+enum TEH_KycTriggerEvent
+{
+
+  /**
+   * Customer withdraws coins.
+   */
+  TEH_KYC_TRIGGER_WITHDRAW = 0,
+
+  /**
+   * Merchant deposits coins.
+   */
+  TEH_KYC_TRIGGER_DEPOSIT = 1,
+
+  /**
+   * Wallet receives P2P payment.
+   */
+  TEH_KYC_TRIGGER_P2P_RECEIVE = 2,
+
+  /**
+   * Wallet balance exceeds threshold.
+   */
+  TEH_KYC_TRIGGER_WALLET_BALANCE = 3
+
+};
+
+
+/**
+ * Parse KYC trigger string value from a string
+ * into enumeration value.
+ *
+ * @param trigger_s string to parse
+ * @param[out] trigger set to the value found
+ * @return #GNUNET_OK on success, #GNUNET_NO if option
+ *         does not exist, #GNUNET_SYSERR if option is
+ *         malformed
+ */
+enum GNUNET_GenericReturnValue
+TEH_kyc_trigger_from_string (const char *trigger_s,
+                             enum TEH_KycTriggerEvent *trigger);
+
+
+/**
+ * Convert KYC trigger value to human-readable string.
+ *
+ * @param trigger value to convert
+ * @return human-readable representation of the @a trigger
+ */
+const char *
+TEH_kyc_trigger2s (enum TEH_KycTriggerEvent trigger);
+
+
+/**
+ * Parse user type string into enumeration value.
+ *
+ * @param ut_s string to parse
+ * @param[out] ut set to the value found
+ * @return #GNUNET_OK on success, #GNUNET_NO if option
+ *         does not exist, #GNUNET_SYSERR if option is
+ *         malformed
+ */
+enum GNUNET_GenericReturnValue
+TEH_kyc_user_type_from_string (const char *ut_s,
+                               enum TEH_KycUserType *ut);
+
+
+/**
+ * Convert KYC user type to human-readable string.
+ *
+ * @param ut value to convert
+ * @return human-readable representation of the @a ut
+ */
+const char *
+TEH_kyc_user_type2s (enum TEH_KycUserType ut);
+
+
+/**
+ * Initialize KYC subsystem. Loads the KYC
+ * configuration.
+ *
+ * @return #GNUNET_OK on success
+ */
+enum GNUNET_GenericReturnValue
+TEH_kyc_init (void);
+
+
+/**
+ * Shut down the KYC subsystem.
+ */
+void
+TEH_kyc_done (void);
+
+
+/**
+ * Function called on each @a amount that was found to
+ * be relevant for a KYC check.
+ *
+ * @param cls closure to allow the KYC module to
+ *        total up amounts and evaluate rules
+ * @param amount encountered transaction amount
+ * @param date when was the amount encountered
+ * @return #GNUNET_OK to continue to iterate,
+ *         #GNUNET_NO to abort iteration
+ *         #GNUNET_SYSERR on internal error (also abort itaration)
+ */
+enum GNUNET_GenericReturnValue
+(*TEH_KycAmountCallback)(void *cls,
+                         const struct TALER_Amount *amount,
+                         struct GNUNET_TIME_Absolute date);
+
+
+/**
+ * Function called to iterate over KYC-relevant
+ * transaction amounts for a particular time range.
+ * Called within a database transaction, so must
+ * not start a new one.
+ *
+ * @param cls closure, identifies the event type and
+ *        account to iterate over events for
+ * @param limit maximum time-range for which events
+ *        should be fetched (timestamp in the past)
+ * @param cb function to call on each event found,
+ *        events must be returned in reverse chronological
+ *        order
+ * @param cb_cls closure for @a cb
+ */
+void
+(*TEH_KycAmountIterator)(void *cls,
+                         struct GNUNET_TIME_Absolute limit,
+                         TEH_KycAmountCallback cb,
+                         void *cb_cls);
+
+
+/**
+ * Check if KYC is provided for a particular operation. Returns the best
+ * provider (configuration section name) that could perform the required
+ * check.
+ *
+ * Called within a database transaction, so must
+ * not start a new one.
+ *
+ * @param event what type of operation is triggering the
+ *         test if KYC is required
+ * @param h_payto account the event is about
+ * @param ai callback offered to inquire about historic
+ *         amounts involved in this type of operation
+ *         at the given account
+ * @param cls closure for @a pi and @a ai
+ * @return NULL if no check is needed
+ */
+const char *
+TEH_kyc_test_required (enum TEH_KycTriggerEvent event,
+                       const struct TALER_PaytoHashP *h_payto,
+                       TEH_KycAmountIterator ai,
+                       void *cls);
+
+
+/**
+ * Obtain the provider logic for a given
+ * @a provider_section_name.
+ *
+ * @param provider_section_name identifies a KYC provider process
+ * @param[out] plugin set to the KYC logic API
+ * @param[out] pd set to the specific operation context
+ * @return #GNUNET_OK on success
+ */
+enum GNUNET_GenericReturnValue
+TEH_kyc_get_logic (const char *provider_section_name,
+                   struct TEH_KYCLOGIC_Plugin **plugin,
+                   struct TEH_KYCLOGIC_ProviderDetails **pd);
+
+
+#endif

src/include/Makefile.am

@@ -17,6 +17,7 @@ talerinclude_HEADERS = \
   taler_exchangedb_plugin.h \
   taler_extensions.h \
   taler_fakebank_lib.h \
+  taler_kyclogic_plugin.h \
   taler_json_lib.h \
   taler_testing_lib.h \
   taler_util.h \

src/include/taler_kyclogic_plugin.h

@@ -0,0 +1,125 @@
+/*
+  This file is part of TALER
+  Copyright (C) 2022 Taler Systems SA
+
+  TALER 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
+  Foundation; either version 3, or (at your option) any later version.
+
+  TALER is distributed in the hope that it will be useful, but WITHOUT ANY
+  WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
+  A PARTICULAR PURPOSE.  See the GNU General Public License for more details.
+
+  You should have received a copy of the GNU General Public License along with
+  TALER; see the file COPYING.  If not, see <http://www.gnu.org/licenses/>
+*/
+/**
+ * @file include/taler_kyclogic_plugin.h
+ * @brief KYC API specific logic C interface
+ * @author Christian Grothoff
+ */
+#ifndef TALER_KYCLOGIC_PLUGIN_H
+#define TALER_KYCLOGIC_PLUGIN_H
+
+#include <jansson.h>
+#include <gnunet/gnunet_util_lib.h>
+
+
+/**
+ * Plugin-internal specification of the configuration
+ * of the plugin for a given KYC provider.
+ */
+struct TEH_KYCLOGIC_ProviderDetails;
+
+/**
+ * Handle for an initiation operation.
+ */
+struct TEH_KYCLOGIC_InitiateHandle;
+
+
+/**
+ * Function called with the result of a KYC initiation
+ * operation.
+ *
+ * @param ec #TALER_EC_NONE on success
+ * @param redirect_url set to where to redirect the user on success, NULL on failure
+ * @param provider_user_id set to user ID at the provider, or NULL if not supported or unknown
+ * @param provider_legitimization_id set to legitimization process ID at the provider, or NULL if not supported or unknown
+ * @param error_msg_hint set to additional details to return to user, NULL on success
+ */
+typedef void
+(*TEH_KYCLOGIC_InitiateCallback)(
+  enum TALER_ErrorCode ec,
+  const char *redirect_url,
+  const char *provider_user_id,
+  const char *provider_legitimization_id,
+  const char *error_msg_hint);
+
+
+/**
+ * @brief The plugin API, returned from the plugin's "init" function.
+ * The argument given to "init" is simply a configuration handle.
+ */
+struct TALER_KYCLOGIC_Plugin
+{
+
+  /**
+   * Closure for all callbacks.
+   */
+  void *cls;
+
+  /**
+   * Name of the library which generated this plugin.  Set by the
+   * plugin loader.
+   */
+  char *library_name;
+
+  /**
+   * Load the configuration of the KYC provider.
+   *
+   * @param provider_section_name configuration section to parse
+   * @return NULL if configuration is invalid
+   */
+  struct TEH_KYCLOGIC_ProviderDetails *
+  (*load_configuration)(const char *provider_section_name);
+
+  /**
+   * Release configuration resources previously loaded
+   *
+   * @param[in] pd configuration to release
+   */
+  void
+  (*unload_configuration)(struct TEH_KYCLOGIC_ProviderDetails *pd);
+
+
+  /**
+   * Initiate KYC check.
+   *
+   * @param cls the @e cls of this struct with the plugin-specific state
+   * @param pd provider configuration details
+   * @param account_id which account to trigger process for
+   * @return handle to cancel operation early
+   */
+  struct TEH_KYCLOGIC_InitiateHandle *
+  (*initiate)(void *cls,
+              const struct TEH_KYCLOGIC_ProviderDetails *pd,
+              const struct TALER_PaytoHashP *account_id,
+              TEH_KYCLOGIC_InitiateCallback cb,
+              void *cb_cls);
+
+  /**
+   * Cancel KYC check initiation.
+   *
+   * @param[in] ih handle of operation to cancel
+   */
+  void
+  (*initiate_cancel) (struct TEH_KYCLOGIC_InitiateHandle *ih);
+
+  // FIXME: add callback pair for kyc_proof
+
+  // FIXME: add callback pair for kyc_webhook
+
+};
+
+
+#endif /* _TALER_KYCLOGIC_PLUGIN_H */