summaryrefslogtreecommitdiff
path: root/src/include
diff options
context:
space:
mode:
authorChristian Grothoff <christian@grothoff.org>2022-08-05 13:32:27 +0200
committerChristian Grothoff <christian@grothoff.org>2022-08-05 13:32:27 +0200
commit4724867794c30ab2d61a2f78ad3f8ad919664519 (patch)
tree9ec29dae36f03940af06dbedd0723e3663dcac0e /src/include
parentc78331b6c23b471bff31b4c05a6b6e1e3e06f42a (diff)
downloadexchange-4724867794c30ab2d61a2f78ad3f8ad919664519.tar.gz
exchange-4724867794c30ab2d61a2f78ad3f8ad919664519.tar.bz2
exchange-4724867794c30ab2d61a2f78ad3f8ad919664519.zip
-first pass at new KYC DB API
Diffstat (limited to 'src/include')
-rw-r--r--src/include/taler_exchangedb_plugin.h104
-rw-r--r--src/include/taler_kyclogic_plugin.h218
2 files changed, 320 insertions, 2 deletions
diff --git a/src/include/taler_exchangedb_plugin.h b/src/include/taler_exchangedb_plugin.h
index 26636d441..f085af35e 100644
--- a/src/include/taler_exchangedb_plugin.h
+++ b/src/include/taler_exchangedb_plugin.h
@@ -5622,6 +5622,110 @@ struct TALER_EXCHANGEDB_Plugin
/**
+ * Insert KYC requirement for @a h_payto account into table.
+ *
+ * @param cls closure
+ * @param provider_section provider that must be checked
+ * @param h_payto account that must be KYC'ed
+ * @param[out] legi_row set to legitimization row for this check
+ * @return database transaction status
+ */
+ enum GNUNET_DB_QueryStatus
+ (*insert_kyc_requirement_for_account)(
+ void *cls,
+ const char *provider_section,
+ const struct TALER_PaytoHashP *h_payto,
+ uint64_t *legi_row);
+
+
+ /**
+ * Update KYC requirement check with provider-linkage and/or
+ * expiration data.
+ *
+ * @param cls closure
+ * @param provider_section provider that must be checked
+ * @param h_payto account that must be KYC'ed
+ * @param provider_account_id provider account ID
+ * @param provider_legitimization_id provider legitimization ID
+ * @param expiration how long is this KYC check set to be valid (in the past if invalid)
+ * @return database transaction status
+ */
+ enum GNUNET_DB_QueryStatus
+ (*update_kyc_requirement_by_row)(
+ void *cls,
+ uint64_t legi_row,
+ const char *provider_section,
+ struct TALER_PaytoHashP *h_payto,
+ const char *provider_account_id,
+ const char *provider_legitimization_id,
+ struct GNUNET_TIME_Absolute expiration);
+
+
+ /**
+ * Lookup KYC provider meta data.
+ *
+ * @param cls closure
+ * @param legi_row legitimization row to lookup
+ * @param[out] provider_section provider that must be checked
+ * @param[out] h_payto account that must be KYC'ed
+ * @param[out] expiration how long is this KYC check set to be valid (in the past if invalid)
+ * @param[out] provider_account_id provider account ID
+ * @param[out] provider_legitimization_id provider legitimization ID
+ * @return database transaction status
+ */
+ enum GNUNET_DB_QueryStatus
+ (*lookup_kyc_requirement_by_row)(
+ void *cls,
+ uint64_t legi_row,
+ char **provider_section,
+ struct TALER_PaytoHashP *h_payto,
+ struct GNUNET_TIME_Absolute *expiration,
+ char **provider_account_id,
+ char **provider_legitimization_id);
+
+
+ /**
+ * Lookup KYC provider meta data.
+ *
+ * @param cls closure
+ * @param provider_section provider that must be checked
+ * @param h_payto account that must be KYC'ed
+ * @param[out] legi_row row with the legitimization data
+ * @param[out] expiration how long is this KYC check set to be valid (in the past if invalid)
+ * @param[out] provider_account_id provider account ID
+ * @param[out] provider_legitimization_id provider legitimization ID
+ * @return database transaction status
+ */
+ enum GNUNET_DB_QueryStatus
+ (*lookup_kyc_requirement_by_account)(
+ void *cls,
+ const char *provider_section,
+ const struct TALER_PaytoHashP *h_payto,
+ uint64_t *legi_row,
+ struct GNUNET_TIME_Absolute *expiration,
+ char **provider_account_id,
+ char **provider_legitimization_id);
+
+
+ /**
+ * Lookup an
+ * @a h_payto by @a provider_legitimization_id.
+ *
+ * @param cls closure
+ * @param provider_section
+ * @param provider_legitimization_id legi to look up
+ * @param[out] h_payto where to write the result
+ * @return database transaction status
+ */
+ enum GNUNET_DB_QueryStatus
+ (*kyc_provider_account_lookup)(
+ void *cls,
+ const char *provider_section,
+ const char *provider_legitimization_id,
+ struct TALER_PaytoHashP *h_payto);
+
+
+ /**
* Call us on KYC processes satisfied for the given
* account.
*
diff --git a/src/include/taler_kyclogic_plugin.h b/src/include/taler_kyclogic_plugin.h
index 403181bf9..bcb132dbc 100644
--- a/src/include/taler_kyclogic_plugin.h
+++ b/src/include/taler_kyclogic_plugin.h
@@ -23,10 +23,81 @@
#include <jansson.h>
#include <gnunet/gnunet_util_lib.h>
+#include <gnunet/gnunet_db_lib.h>
#include "taler_util.h"
/**
+ * Possible states of a KYC check.
+ */
+enum TALER_KYCLOGIC_KycStatus
+{
+
+ /**
+ * The provider has passed the customer.
+ */
+ TALER_KYCLOGIC_STATUS_SUCCESS = 0,
+
+ /**
+ * Something to do with the user (bit!).
+ */
+ TALER_KYCLOGIC_STATUS_USER = 1,
+
+ /**
+ * Something to do with the provider (bit!).
+ */
+ TALER_KYCLOGIC_STATUS_PROVIDER = 2,
+
+ /**
+ * The interaction ended in definitive failure.
+ * (kind of with both parties).
+ */
+ TALER_KYCLOGIC_STATUS_FAILED
+ = TALER_KYCLOGIC_STATUS_USER
+ | TALER_KYCLOGIC_STATUS_PROVIDER,
+
+ /**
+ * The interaction is still ongoing.
+ */
+ TALER_KYCLOGIC_STATUS_PENDING = 4,
+
+ /**
+ * One of the parties hat a temporary failure.
+ */
+ TALER_KYCLOGIC_STATUS_ABORTED = 8,
+
+ /**
+ * The interaction with the user is ongoing.
+ */
+ TALER_KYCLOGIC_STATUS_USER_PENDING
+ = TALER_KYCLOGIC_STATUS_USER
+ | TALER_KYCLOGIC_STATUS_PENDING,
+
+ /**
+ * The provider is still checking.
+ */
+ TALER_KYCLOGIC_STATUS_PROVIDER_PENDING
+ = TALER_KYCLOGIC_STATUS_PROVIDER
+ | TALER_KYCLOGIC_STATUS_PENDING,
+
+ /**
+ * The user aborted the check (possibly recoverable).
+ */
+ TALER_KYCLOGIC_STATUS_USER_ABORTED
+ = TALER_KYCLOGIC_STATUS_USER
+ | TALER_KYCLOGIC_STATUS_ABORTED,
+
+ /**
+ * The provider had an (internal) failure.
+ */
+ TALER_KYCLOGIC_STATUS_PROVIDER_FAILED
+ = TALER_KYCLOGIC_STATUS_PROVIDER
+ | TALER_KYCLOGIC_STATUS_ABORTED,
+
+};
+
+
+/**
* Plugin-internal specification of the configuration
* of the plugin for a given KYC provider.
*/
@@ -37,6 +108,16 @@ struct TALER_KYCLOGIC_ProviderDetails;
*/
struct TALER_KYCLOGIC_InitiateHandle;
+/**
+ * Handle for an KYC proof operation.
+ */
+struct TALER_KYCLOGIC_ProofHandle;
+
+/**
+ * Handle for an KYC Web hook operation.
+ */
+struct TALER_KYCLOGIC_WebhookHandle;
+
/**
* Function called with the result of a KYC initiation
@@ -58,6 +139,72 @@ typedef void
/**
+ * Function called with the result of a proof check
+ * operation.
+ *
+ * Note that the "decref" for the @a response
+ * will be done by the plugin.
+ *
+ * @param cls closure
+ * @param status KYC status
+ * @param expiration until when is the KYC check valid
+ * @param http_status HTTP status code of @a response
+ * @param[in] response to return to the HTTP client
+ */
+typedef void
+(*TALER_KYCLOGIC_ProofCallback)(
+ void *cls,
+ enum TALER_KYCLOGIC_KycStatus status,
+ struct GNUNET_TIME_Absolute expiration,
+ unsigned int http_status,
+ struct MHD_Response *response);
+
+
+/**
+ * Function called with the result of a webhook
+ * operation.
+ *
+ * Note that the "decref" for the @a response
+ * will be done by the plugin.
+ *
+ * @param cls closure
+ * @param account_id account the webhook was about
+ * @param status KYC status
+ * @param expiration until when is the KYC check valid
+ * @param http_status HTTP status code of @a response
+ * @param[in] response to return to the HTTP client
+ */
+typedef void
+(*TALER_KYCLOGIC_WebhookCallback)(
+ void *cls,
+ const struct TALER_PaytoHashP *account_id,
+ enum TALER_KYCLOGIC_KycStatus status,
+ struct GNUNET_TIME_Absolute expiration,
+ unsigned int http_status,
+ struct MHD_Response *response);
+
+
+/**
+ * Function the plugin can use to lookup an
+ * @a h_payto by @a provider_legitimization_id.
+ * Must match the `kyc_provider_account_lookup`
+ * of the exchange's database plugin.
+ *
+ * @param cls closure
+ * @param provider_section
+ * @param provider_legitimization_id legi to look up
+ * @param[out] h_payto where to write the result
+ * @return database transaction status
+ */
+typedef enum GNUNET_DB_QueryStatus
+(*TALER_KYCLOGIC_ProviderLookupCallback)(
+ void *cls,
+ const char *provider_section,
+ const char *provider_legitimization_id,
+ struct TALER_PaytoHashP *h_payto);
+
+
+/**
* @brief The plugin API, returned from the plugin's "init" function.
* The argument given to "init" is simply a configuration handle.
*/
@@ -101,6 +248,8 @@ struct TALER_KYCLOGIC_Plugin
* @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
+ * @param cb function to call with the result
+ * @param cb_cls closure for @a cb
* @return handle to cancel operation early
*/
struct TALER_KYCLOGIC_InitiateHandle *
@@ -110,6 +259,7 @@ struct TALER_KYCLOGIC_Plugin
TALER_KYCLOGIC_InitiateCallback cb,
void *cb_cls);
+
/**
* Cancel KYC check initiation.
*
@@ -118,9 +268,73 @@ struct TALER_KYCLOGIC_Plugin
void
(*initiate_cancel) (struct TALER_KYCLOGIC_InitiateHandle *ih);
- // FIXME: add callback pair for kyc_proof
- // FIXME: add callback pair for kyc_webhook
+ /**
+ * Check KYC status and return status to human.
+ *
+ * @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
+ * @param cb function to call with the result
+ * @param cb_cls closure for @a cb
+ * @return handle to cancel operation early
+ */
+ struct TALER_KYCLOGIC_ProofHandle *
+ (*proof)(void *cls,
+ const struct TALER_KYCLOGIC_ProviderDetails *pd,
+ const struct TALER_PaytoHashP *account_id,
+ const char *provider_user_id,
+ const char *provider_legitimization_id,
+ TALER_KYCLOGIC_ProofCallback cb,
+ void *cb_cls);
+
+
+ /**
+ * Cancel KYC proof.
+ *
+ * @param[in] ph handle of operation to cancel
+ */
+ void
+ (*proof_cancel) (struct TALER_KYCLOGIC_ProofHandle *ph);
+
+
+ /**
+ * Check KYC status and return result for Webhook.
+ *
+ * @param cls the @e cls of this struct with the plugin-specific state
+ * @param pd provider configuration details
+ * @param plc callback to lookup accounts with
+ * @param plc_cls closure for @a plc
+ * @param http_method HTTP method used for the webhook
+ * @param url_path rest of the URL after `/kyc-webhook/`
+ * @param connection MHD connection object (for HTTP headers)
+ * @param body_size number of bytes in @a body
+ * @param body HTTP request body
+ * @param cb function to call with the result
+ * @param cb_cls closure for @a cb
+ * @return handle to cancel operation early
+ */
+ struct TALER_KYCLOGIC_InitiateHandle *
+ (*webhook)(void *cls,
+ const struct TALER_KYCLOGIC_ProviderDetails *pd,
+ TALER_KYCLOGIC_ProviderLookupCallback plc,
+ void *plc_cls,
+ const char *http_method,
+ const char *url_path,
+ struct MHD_Connection *connection,
+ size_t body_size,
+ const void *body,
+ TALER_KYCLOGIC_WebhookCallback cb,
+ void *cb_cls);
+
+
+ /**
+ * Cancel KYC webhook execution.
+ *
+ * @param[in] wh handle of operation to cancel
+ */
+ void
+ (*webhook_cancel) (struct TALER_KYCLOGIC_WebhookHandle *wh);
};