summaryrefslogtreecommitdiff
path: root/src/include/taler_kyclogic_lib.h
diff options
context:
space:
mode:
Diffstat (limited to 'src/include/taler_kyclogic_lib.h')
-rw-r--r--src/include/taler_kyclogic_lib.h374
1 files changed, 374 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..4d0c18fa4
--- /dev/null
+++ b/src/include/taler_kyclogic_lib.h
@@ -0,0 +1,374 @@
+/*
+ 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,
+
+ /**
+ * Reserve is being closed by force.
+ */
+ TALER_KYCLOGIC_KYC_TRIGGER_RESERVE_CLOSE = 4,
+
+ /**
+ * Customer withdraws coins via age-withdraw.
+ */
+ TALER_KYCLOGIC_KYC_TRIGGER_AGE_WITHDRAW = 5,
+};
+
+
+/**
+ * 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);
+
+
+/**
+ * Function called to iterate over KYC-relevant
+ * transaction thresholds amounts.
+ *
+ * @param cls closure, identifies the event type and
+ * account to iterate over events for
+ * @param threshold a relevant threshold amount
+ */
+typedef void
+(*TALER_KYCLOGIC_KycThresholdIterator)(void *cls,
+ const struct TALER_Amount *threshold);
+
+
+/**
+ * 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 set of checks that still need to be satisfied.
+ *
+ * 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
+ * @param[out] required set to NULL if no check is needed,
+ * otherwise space-separated list of required checks
+ * @return transaction status
+ */
+enum GNUNET_DB_QueryStatus
+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,
+ char **required);
+
+
+/**
+ * Check if the @a requirements are now satsified for
+ * @a h_payto account.
+ *
+ * @param[in,out] requirements space-spearated list of requirements,
+ * already satisfied requirements are removed from the list
+ * @param h_payto hash over the account
+ * @param[out] kyc_details if satisfied, set to what kind of
+ * KYC information was collected
+ * @param ki iterator over satisfied providers
+ * @param ki_cls closure for @a ki
+ * @param[out] satisfied set to true if the KYC check was satisfied
+ * @return transaction status (from @a ki)
+ */
+enum GNUNET_DB_QueryStatus
+TALER_KYCLOGIC_check_satisfied (char **requirements,
+ const struct TALER_PaytoHashP *h_payto,
+ json_t **kyc_details,
+ TALER_KYCLOGIC_KycSatisfiedIterator ki,
+ void *ki_cls,
+ bool *satisfied);
+
+
+/**
+ * Iterate over all thresholds that are applicable
+ * to a particular type of @a event
+ *
+ * @param event thresholds to look up
+ * @param it function to call on each
+ * @param it_cls closure for @a it
+ */
+void
+TALER_KYCLOGIC_kyc_iterate_thresholds (
+ enum TALER_KYCLOGIC_KycTriggerEvent event,
+ TALER_KYCLOGIC_KycThresholdIterator it,
+ void *it_cls);
+
+
+/**
+ * Function called with the provider details and
+ * associated plugin closures for matching logics.
+ *
+ * @param cls closure
+ * @param pd provider details of a matching logic
+ * @param plugin_cls closure of the plugin
+ * @return #GNUNET_OK to continue to iterate
+ */
+typedef enum GNUNET_GenericReturnValue
+(*TALER_KYCLOGIC_DetailsCallback)(
+ void *cls,
+ const struct TALER_KYCLOGIC_ProviderDetails *pd,
+ void *plugin_cls);
+
+
+/**
+ * Call @a cb for all logics with name @a logic_name,
+ * providing the plugin closure and the @a pd configurations.
+ *
+ * @param logic_name name of the logic to match
+ * @param cb function to call on matching results
+ * @param cb_cls closure for @a cb
+ */
+void
+TALER_KYCLOGIC_kyc_get_details (
+ const char *logic_name,
+ TALER_KYCLOGIC_DetailsCallback cb,
+ void *cb_cls);
+
+
+/**
+ * Check if a given @a check_name is a legal name (properly
+ * configured) and can be satisfied in principle.
+ *
+ * @param check_name name of the check to see if it is configured
+ * @return #GNUNET_OK if the check can be satisfied,
+ * #GNUNET_NO if the check can never be satisfied,
+ * #GNUNET_SYSERR if the type of the check is unknown
+ */
+enum GNUNET_GenericReturnValue
+TALER_KYCLOGIC_check_satisfiable (
+ const char *check_name);
+
+
+/**
+ * Return list of all KYC checks that are possible.
+ *
+ * @return JSON array of strings with the allowed KYC checks
+ */
+json_t *
+TALER_KYCLOGIC_get_satisfiable (void);
+
+
+/**
+ * Obtain the provider logic for a given set of @a requirements.
+ *
+ * @param requirements space-separated list of required checks
+ * @param ut type of the entity performing the check
+ * @param[out] plugin set to the KYC logic API
+ * @param[out] pd set to the specific operation context
+ * @param[out] configuration_section set to the name of the KYC logic configuration section * @return #GNUNET_OK on success
+ */
+enum GNUNET_GenericReturnValue
+TALER_KYCLOGIC_requirements_to_logic (const char *requirements,
+ enum TALER_KYCLOGIC_KycUserType ut,
+ struct TALER_KYCLOGIC_Plugin **plugin,
+ struct TALER_KYCLOGIC_ProviderDetails **pd,
+ const char **configuration_section);
+
+
+/**
+ * Obtain the provider logic for a given @a name.
+ *
+ * @param name name of the logic or provider section
+ * @param[out] plugin set to the KYC logic API
+ * @param[out] pd set to the specific operation context
+ * @param[out] configuration_section set to the name of the KYC logic configuration section
+ * @return #GNUNET_OK on success
+ */
+enum GNUNET_GenericReturnValue
+TALER_KYCLOGIC_lookup_logic (const char *name,
+ struct TALER_KYCLOGIC_Plugin **plugin,
+ struct TALER_KYCLOGIC_ProviderDetails **pd,
+ const char **configuration_section);
+
+
+/**
+ * Obtain array of KYC checks provided by the provider
+ * configured in @a section_name.
+ *
+ * @param section_name configuration section name
+ * @param[out] num_checks set to the length of the array
+ * @param[out] provided_checks set to an array with the
+ * names of the checks provided by this KYC provider
+ */
+void
+TALER_KYCLOGIC_lookup_checks (const char *section_name,
+ unsigned int *num_checks,
+ char ***provided_checks);
+
+#endif