1 files changed, 384 insertions, 0 deletions
diff --git a/src/include/taler_kyclogic_plugin.h b/src/include/taler_kyclogic_plugin.h
new file mode 100644
index 000000000..a9a4dd97a
--- /dev/null
+++ b/src/include/taler_kyclogic_plugin.h
@@ -0,0 +1,384 @@
+/*
+  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>
+#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)
+   * or made some other type of (recoverable) mistake.
+   */
+  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,
+
+  /**
+   * Return code set to not update the KYC status
+   * at all.
+   */
+  TALER_KYCLOGIC_STATUS_KEEP = 16,
+
+  /**
+   * We had an internal logic failure.
+   */
+  TALER_KYCLOGIC_STATUS_INTERNAL_ERROR = 32
+
+};
+
+
+/**
+ * Plugin-internal specification of the configuration
+ * of the plugin for a given KYC provider.
+ */
+struct TALER_KYCLOGIC_ProviderDetails;
+
+/**
+ * Handle for an initiation operation.
+ */
+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
+ * operation.
+ *
+ * @param cls closure
+ * @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
+(*TALER_KYCLOGIC_InitiateCallback)(
+  void *cls,
+  enum TALER_ErrorCode ec,
+  const char *redirect_url,
+  const char *provider_user_id,
+  const char *provider_legitimization_id,
+  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 callee and MUST NOT be done by the plugin.
+ *
+ * @param cls closure
+ * @param status KYC status
+ * @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 attributes user attributes returned by the provider
+ * @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,
+  const char *provider_user_id,
+  const char *provider_legitimization_id,
+  struct GNUNET_TIME_Absolute expiration,
+  const json_t *attributes,
+  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 callee and
+ * MUST NOT be done by the plugin!
+ *
+ * @param cls closure
+ * @param process_row legitimization process the webhook was about
+ * @param account_id account the webhook was about
+ * @param provider_section name of the configuration section of the logic that was run
+ * @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 status KYC status
+ * @param expiration until when is the KYC check valid
+ * @param attributes user attributes returned by the provider
+ * @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,
+  uint64_t process_row,
+  const struct TALER_PaytoHashP *account_id,
+  const char *provider_section,
+  const char *provider_user_id,
+  const char *provider_legitimization_id,
+  enum TALER_KYCLOGIC_KycStatus status,
+  struct GNUNET_TIME_Absolute expiration,
+  const json_t *attributes,
+  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
+ * @param[out] process_row where to write the row of the entry
+ * @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,
+  uint64_t *process_row);
+
+
+/**
+ * @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;
+
+  /**
+   * Name of the logic, for webhook matching. Set by the
+   * plugin loader.
+   */
+  char *name;
+
+  /**
+   * Load the configuration of the KYC provider.
+   *
+   * @param cls closure
+   * @param provider_section_name configuration section to parse
+   * @return NULL if configuration is invalid
+   */
+  struct TALER_KYCLOGIC_ProviderDetails *
+  (*load_configuration)(void *cls,
+                        const char *provider_section_name);
+
+  /**
+   * Release configuration resources previously loaded
+   *
+   * @param[in] pd configuration to release
+   */
+  void
+  (*unload_configuration)(struct TALER_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
+   * @param process_row unique ID for the legitimization process
+   * @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 *
+  (*initiate)(void *cls,
+              const struct TALER_KYCLOGIC_ProviderDetails *pd,
+              const struct TALER_PaytoHashP *account_id,
+              uint64_t process_row,
+              TALER_KYCLOGIC_InitiateCallback cb,
+              void *cb_cls);
+
+
+  /**
+   * Cancel KYC check initiation.
+   *
+   * @param[in] ih handle of operation to cancel
+   */
+  void
+  (*initiate_cancel) (struct TALER_KYCLOGIC_InitiateHandle *ih);
+
+
+  /**
+   * 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 connection MHD connection object (for HTTP headers)
+   * @param account_id which account to trigger process for
+   * @param process_row row in the legitimization processes table the legitimization is for
+   * @param provider_user_id user ID (or NULL) the proof is for
+   * @param provider_legitimization_id legitimization ID the proof is 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,
+           struct MHD_Connection *connection,
+           const struct TALER_PaytoHashP *account_id,
+           uint64_t process_row,
+           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/$LOGIC/`
+   * @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_WebhookHandle *
+  (*webhook)(void *cls,
+             const struct TALER_KYCLOGIC_ProviderDetails *pd,
+             TALER_KYCLOGIC_ProviderLookupCallback plc,
+             void *plc_cls,
+             const char *http_method,
+             const char *const url_path[],
+             struct MHD_Connection *connection,
+             const json_t *upload,
+             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);
+
+};
+
+
+#endif /* _TALER_KYCLOGIC_PLUGIN_H */