From 4724867794c30ab2d61a2f78ad3f8ad919664519 Mon Sep 17 00:00:00 2001 From: Christian Grothoff Date: Fri, 5 Aug 2022 13:32:27 +0200 Subject: -first pass at new KYC DB API --- src/include/taler_exchangedb_plugin.h | 104 ++++++++++++++++ src/include/taler_kyclogic_plugin.h | 218 +++++++++++++++++++++++++++++++++- 2 files changed, 320 insertions(+), 2 deletions(-) (limited to 'src/include') 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 @@ -5621,6 +5621,110 @@ struct TALER_EXCHANGEDB_Plugin uint64_t serial); + /** + * 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,9 +23,80 @@ #include #include +#include #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 @@ -57,6 +138,72 @@ typedef void const char *error_msg_hint); +/** + * 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); }; -- cgit v1.2.3