1 files changed, 226 insertions, 0 deletions
diff --git a/src/include/taler_kyclogic_lib.h b/src/include/taler_kyclogic_lib.h
new file mode 100644
index 000000000..6b54276f6
--- /dev/null
+++ b/src/include/taler_kyclogic_lib.h
@@ -0,0 +1,226 @@
+/*
+  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_kyclogic_lib.h
+ * @brief server-side KYC API
+ * @author Christian Grothoff
+ */
+#ifndef TALER_KYCLOGIC_LIB_H
+#define TALER_KYCLOGIC_LIB_H
+
+#include <microhttpd.h>
+#include <taler_exchangedb_plugin.h>
+#include <taler_kyclogic_plugin.h>
+
+
+/**
+ * Enumeration for our KYC user types.
+ */
+enum TALER_KYCLOGIC_KycUserType
+{
+  /**
+   * KYC rule is for an individual.
+   */
+  TALER_KYCLOGIC_KYC_UT_INDIVIDUAL = 0,
+
+  /**
+   * KYC rule is for a business.
+   */
+  TALER_KYCLOGIC_KYC_UT_BUSINESS = 1
+};
+
+
+/**
+ * Enumeration of possible events that may trigger
+ * KYC requirements.
+ */
+enum TALER_KYCLOGIC_KycTriggerEvent
+{
+
+  /**
+   * Customer withdraws coins.
+   */
+  TALER_KYCLOGIC_KYC_TRIGGER_WITHDRAW = 0,
+
+  /**
+   * Merchant deposits coins.
+   */
+  TALER_KYCLOGIC_KYC_TRIGGER_DEPOSIT = 1,
+
+  /**
+   * Wallet receives P2P payment.
+   */
+  TALER_KYCLOGIC_KYC_TRIGGER_P2P_RECEIVE = 2,
+
+  /**
+   * Wallet balance exceeds threshold.
+   */
+  TALER_KYCLOGIC_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
+TALER_KYCLOGIC_kyc_trigger_from_string (
+  const char *trigger_s,
+  enum TALER_KYCLOGIC_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 *
+TALER_KYCLOGIC_kyc_trigger2s (enum TALER_KYCLOGIC_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
+TALER_KYCLOGIC_kyc_user_type_from_string (const char *ut_s,
+                                          enum TALER_KYCLOGIC_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 *
+TALER_KYCLOGIC_kyc_user_type2s (enum TALER_KYCLOGIC_KycUserType ut);
+
+
+/**
+ * Initialize KYC subsystem. Loads the KYC configuration.
+ *
+ * @param cfg configuration to parse
+ * @return #GNUNET_OK on success
+ */
+enum GNUNET_GenericReturnValue
+TALER_KYCLOGIC_kyc_init (const struct GNUNET_CONFIGURATION_Handle *cfg);
+
+
+/**
+ * Shut down the KYC subsystem.
+ */
+void
+TALER_KYCLOGIC_kyc_done (void);
+
+
+/**
+ * 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
+ */
+typedef void
+(*TALER_KYCLOGIC_KycAmountIterator)(void *cls,
+                                    struct GNUNET_TIME_Absolute limit,
+                                    TALER_EXCHANGEDB_KycAmountCallback cb,
+                                    void *cb_cls);
+
+
+/**
+ * Call us on KYC processes satisfied for the given
+ * account. Must match the ``select_satisfied_kyc_processes`` of the exchange database plugin.
+ *
+ * @param cls the @e cls of this struct with the plugin-specific state
+ * @param h_payto account identifier
+ * @param spc function to call for each satisfied KYC process
+ * @param spc_cls closure for @a spc
+ * @return transaction status code
+ */
+typedef enum GNUNET_DB_QueryStatus
+(*TALER_KYCLOGIC_KycSatisfiedIterator)(
+  void *cls,
+  const struct TALER_PaytoHashP *h_payto,
+  TALER_EXCHANGEDB_SatisfiedProviderCallback spc,
+  void *spc_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 ki callback that returns list of already
+ *    satisfied KYC checks, implemented by ``select_satisfied_kyc_processes`` of the exchangedb
+ * @param ki_cls closure for @a ki
+ * @param ai callback offered to inquire about historic
+ *         amounts involved in this type of operation
+ *         at the given account
+ * @param ai_cls closure for @a ai
+ * @return NULL if no check is needed
+ */
+const char *
+TALER_KYCLOGIC_kyc_test_required (enum TALER_KYCLOGIC_KycTriggerEvent event,
+                                  const struct TALER_PaytoHashP *h_payto,
+                                  TALER_KYCLOGIC_KycSatisfiedIterator ki,
+                                  void *ki_cls,
+                                  TALER_KYCLOGIC_KycAmountIterator ai,
+                                  void *ai_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
+TALER_KYCLOGIC_kyc_get_logic (const char *provider_section_name,
+                              struct TALER_KYCLOGIC_Plugin **plugin,
+                              struct TALER_KYCLOGIC_ProviderDetails **pd);
+
+
+#endif