commit 3defe9e41069acfbc24a96473d827d82f9e71a04
parent 02d3e378dc4c49b2444b45311f87e98dd97a90ec
Author: Christian Grothoff <christian@grothoff.org>
Date: Sun, 7 Jun 2026 23:34:49 +0200
add API for POST /kyc-upload/
Diffstat:
5 files changed, 423 insertions(+), 48 deletions(-)
diff --git a/src/include/taler/exchange/meson.build b/src/include/taler/exchange/meson.build
@@ -26,6 +26,7 @@ talerexchange_headers = [
'post-blinding-prepare.h',
'post-coins-COIN_PUB-refund.h',
'post-kyc-start-ID.h',
+ 'post-kyc-upload-ID.h',
'post-kyc-wallet.h',
'post-management-aml-officers.h',
'post-management-auditors.h',
diff --git a/src/include/taler/exchange/post-kyc-upload-ID.h b/src/include/taler/exchange/post-kyc-upload-ID.h
@@ -0,0 +1,125 @@
+/*
+ This file is part of TALER
+ Copyright (C) 2014-2026 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 include/taler/exchange/post-kyc-upload-ID.h
+ * @brief C interface for POST /kyc-upload/$ID
+ * @author Christian Grothoff
+ */
+#ifndef _TALER_EXCHANGE__POST_KYC_UPLOAD_ID_H
+#define _TALER_EXCHANGE__POST_KYC_UPLOAD_ID_H
+
+#include <taler/exchange/common.h>
+
+/**
+ * Handle for an operation to POST /kyc-upload/$ID.
+ */
+struct TALER_EXCHANGE_PostKycUploadHandle;
+
+
+/**
+ * Set up POST /kyc-upload/$ID operation.
+ * Note that you must explicitly start the operation after setup.
+ *
+ * @param ctx CURL context
+ * @param url exchange base URL
+ * @param id identifier for the KYC process the upload is for
+ * @param attributes the client-provided evidence to upload; a
+ * `CustomerKycAttributes` object that depends on the form
+ * being submitted, but MUST include the form ID
+ * @return handle to operation, NULL on error
+ */
+struct TALER_EXCHANGE_PostKycUploadHandle *
+TALER_EXCHANGE_post_kyc_upload_create (
+ struct GNUNET_CURL_Context *ctx,
+ const char *url,
+ const char *id,
+ const json_t *attributes);
+
+
+/**
+ * KYC upload response details.
+ */
+struct TALER_EXCHANGE_PostKycUploadResponse
+{
+ /**
+ * HTTP response data
+ */
+ struct TALER_EXCHANGE_HttpResponse hr;
+
+ /**
+ * Details depending on @e hr.http_status.
+ */
+ union
+ {
+ /**
+ * Empty, @e hr.http_status is #MHD_HTTP_NO_CONTENT.
+ */
+ char empty[0];
+
+ } details;
+
+};
+
+
+#ifndef TALER_EXCHANGE_POST_KYC_UPLOAD_RESULT_CLOSURE
+/**
+ * Type of the closure used by
+ * the #TALER_EXCHANGE_PostKycUploadCallback.
+ */
+#define TALER_EXCHANGE_POST_KYC_UPLOAD_RESULT_CLOSURE void
+#endif /* TALER_EXCHANGE_POST_KYC_UPLOAD_RESULT_CLOSURE */
+
+/**
+ * Type of the function that receives the result of a
+ * POST /kyc-upload/$ID request.
+ *
+ * @param cls closure
+ * @param result result returned by the HTTP server
+ */
+typedef void
+(*TALER_EXCHANGE_PostKycUploadCallback)(
+ TALER_EXCHANGE_POST_KYC_UPLOAD_RESULT_CLOSURE *cls,
+ const struct TALER_EXCHANGE_PostKycUploadResponse *result);
+
+
+/**
+ * Start POST /kyc-upload/$ID operation.
+ *
+ * @param[in,out] pksh operation to start
+ * @param cb function to call with the exchange's result
+ * @param cb_cls closure for @a cb
+ * @return status code, #TALER_EC_NONE on success
+ */
+enum TALER_ErrorCode
+TALER_EXCHANGE_post_kyc_upload_start (
+ struct TALER_EXCHANGE_PostKycUploadHandle *pksh,
+ TALER_EXCHANGE_PostKycUploadCallback cb,
+ TALER_EXCHANGE_POST_KYC_UPLOAD_RESULT_CLOSURE *cb_cls);
+
+
+/**
+ * Cancel POST /kyc-upload/$ID operation. This function must not be called by
+ * clients after the TALER_EXCHANGE_PostKycUploadCallback has been invoked (as
+ * in those cases it'll be called internally by the implementation already).
+ *
+ * @param[in] pksh operation to cancel
+ */
+void
+TALER_EXCHANGE_post_kyc_upload_cancel (
+ struct TALER_EXCHANGE_PostKycUploadHandle *pksh);
+
+
+#endif /* _TALER_EXCHANGE__POST_KYC_UPLOAD_ID_H */
diff --git a/src/include/taler/taler_exchange_service.h b/src/include/taler/taler_exchange_service.h
@@ -34,59 +34,60 @@
#include <taler/exchange/common.h> /* UNNECESSARY? */
#include <taler/exchange/get-keys.h>
#include <taler/exchange/post-batch-deposit.h>
-#include <taler/exchange/post-coins-COIN_PUB-refund.h> /* UNNECESSARY? */
-#include <taler/exchange/get-coins-COIN_PUB-history.h> /* UNNECESSARY? */
-#include <taler/exchange/get-reserves-RESERVE_PUB-history.h> /* UNNECESSARY? */
-#include <taler/exchange/post-blinding-prepare.h> /* UNNECESSARY? */
-#include <taler/exchange/post-withdraw.h> /* UNNECESSARY? */
-#include <taler/exchange/post-withdraw_blinded.h> /* UNNECESSARY? */
-#include <taler/exchange/post-reveal-withdraw.h> /* UNNECESSARY? */
-#include <taler/exchange/post-reveal-melt.h> /* UNNECESSARY? */
-#include <taler/exchange/post-melt.h> /* UNNECESSARY? */
-#include <taler/exchange/get-transfers-WTID.h> /* UNNECESSARY? */
+#include <taler/exchange/post-coins-COIN_PUB-refund.h>
+#include <taler/exchange/get-coins-COIN_PUB-history.h>
+#include <taler/exchange/get-reserves-RESERVE_PUB-history.h>
+#include <taler/exchange/post-blinding-prepare.h>
+#include <taler/exchange/post-withdraw.h>
+#include <taler/exchange/post-withdraw_blinded.h>
+#include <taler/exchange/post-reveal-withdraw.h>
+#include <taler/exchange/post-reveal-melt.h>
+#include <taler/exchange/post-melt.h>
+#include <taler/exchange/get-transfers-WTID.h>
#include \
<taler/exchange/get-deposits-H_WIRE-MERCHANT_PUB-H_CONTRACT_TERMS-COIN_PUB.h>
-#include <taler/exchange/post-recoup-withdraw.h> /* UNNECESSARY? */
-#include <taler/exchange/post-recoup-refresh.h> /* UNNECESSARY? */
-#include <taler/exchange/get-kyc-check-H_NORMALIZED_PAYTO.h> /* UNNECESSARY? */
-#include <taler/exchange/get-kyc-info-ACCESS_TOKEN.h> /* UNNECESSARY? */
-#include <taler/exchange/post-kyc-start-ID.h> /* UNNECESSARY? */
-#include <taler/exchange/get-kyc-proof-PROVIDER_NAME.h> /* UNNECESSARY? */
-#include <taler/exchange/post-kyc-wallet.h> /* UNNECESSARY? */
-#include <taler/exchange/get-management-keys.h> /* UNNECESSARY? */
-#include <taler/exchange/post-management-keys.h> /* UNNECESSARY? */
-#include <taler/exchange/post-management-drain.h> /* UNNECESSARY? */
+#include <taler/exchange/post-recoup-withdraw.h>
+#include <taler/exchange/post-recoup-refresh.h>
+#include <taler/exchange/get-kyc-check-H_NORMALIZED_PAYTO.h>
+#include <taler/exchange/get-kyc-info-ACCESS_TOKEN.h>
+#include <taler/exchange/post-kyc-start-ID.h>
+#include <taler/exchange/post-kyc-upload-ID.h>
+#include <taler/exchange/get-kyc-proof-PROVIDER_NAME.h>
+#include <taler/exchange/post-kyc-wallet.h>
+#include <taler/exchange/get-management-keys.h>
+#include <taler/exchange/post-management-keys.h>
+#include <taler/exchange/post-management-drain.h>
#include \
<taler/exchange/post-management-denominations-H_DENOM_PUB-revoke.h>
-#include <taler/exchange/post-management-signkeys-EXCHANGE_PUB-revoke.h> /* UNNECESSARY? */
-#include <taler/exchange/post-management-aml-officers.h> /* UNNECESSARY? */
-#include <taler/exchange/get-aml-OFFICER_PUB-measures.h> /* UNNECESSARY? */
-#include <taler/exchange/get-aml-OFFICER_PUB-kyc-statistics-NAMES.h> /* UNNECESSARY? */
-#include <taler/exchange/post-aml-OFFICER_PUB-decision.h> /* UNNECESSARY? */
-#include <taler/exchange/post-management-partners.h> /* UNNECESSARY? */
-#include <taler/exchange/post-management-auditors.h> /* UNNECESSARY? */
-#include <taler/exchange/post-management-auditors-AUDITOR_PUB-disable.h> /* UNNECESSARY? */
-#include <taler/exchange/post-management-wire.h> /* UNNECESSARY? */
-#include <taler/exchange/post-management-wire-disable.h> /* UNNECESSARY? */
-#include <taler/exchange/post-management-wire-fee.h> /* UNNECESSARY? */
-#include <taler/exchange/post-management-global-fees.h> /* UNNECESSARY? */
-#include <taler/exchange/post-auditors-AUDITOR_PUB-H_DENOM_PUB.h> /* UNNECESSARY? */
-#include <taler/exchange/get-contracts-CONTRACT_PUB.h> /* UNNECESSARY? */
-#include <taler/exchange/get-purses-PURSE_PUB-merge.h> /* UNNECESSARY? */
-#include <taler/exchange/post-purses-PURSE_PUB-create.h> /* UNNECESSARY? */
-#include <taler/exchange/delete-purses-PURSE_PUB.h> /* UNNECESSARY? */
-#include <taler/exchange/post-purses-PURSE_PUB-merge.h> /* UNNECESSARY? */
-#include <taler/exchange/post-reserves-RESERVE_PUB-purse.h> /* UNNECESSARY? */
-#include <taler/exchange/post-purses-PURSE_PUB-deposit.h> /* UNNECESSARY? */
-#include <taler/exchange/post-reserves-RESERVE_PUB-open.h> /* UNNECESSARY? */
-#include <taler/exchange/get-reserves-attest-RESERVE_PUB.h> /* UNNECESSARY? */
-#include <taler/exchange/post-reserves-attest-RESERVE_PUB.h> /* UNNECESSARY? */
-#include <taler/exchange/post-reserves-RESERVE_PUB-close.h> /* UNNECESSARY? */
-#include <taler/exchange/get-reserves-RESERVE_PUB.h> /* UNNECESSARY? */
-#include <taler/exchange/get-aml-OFFICER_PUB-legitimizations.h> /* UNNECESSARY? */
+#include <taler/exchange/post-management-signkeys-EXCHANGE_PUB-revoke.h>
+#include <taler/exchange/post-management-aml-officers.h>
+#include <taler/exchange/get-aml-OFFICER_PUB-measures.h>
+#include <taler/exchange/get-aml-OFFICER_PUB-kyc-statistics-NAMES.h>
+#include <taler/exchange/post-aml-OFFICER_PUB-decision.h>
+#include <taler/exchange/post-management-partners.h>
+#include <taler/exchange/post-management-auditors.h>
+#include <taler/exchange/post-management-auditors-AUDITOR_PUB-disable.h>
+#include <taler/exchange/post-management-wire.h>
+#include <taler/exchange/post-management-wire-disable.h>
+#include <taler/exchange/post-management-wire-fee.h>
+#include <taler/exchange/post-management-global-fees.h>
+#include <taler/exchange/post-auditors-AUDITOR_PUB-H_DENOM_PUB.h>
+#include <taler/exchange/get-contracts-CONTRACT_PUB.h>
+#include <taler/exchange/get-purses-PURSE_PUB-merge.h>
+#include <taler/exchange/post-purses-PURSE_PUB-create.h>
+#include <taler/exchange/delete-purses-PURSE_PUB.h>
+#include <taler/exchange/post-purses-PURSE_PUB-merge.h>
+#include <taler/exchange/post-reserves-RESERVE_PUB-purse.h>
+#include <taler/exchange/post-purses-PURSE_PUB-deposit.h>
+#include <taler/exchange/post-reserves-RESERVE_PUB-open.h>
+#include <taler/exchange/get-reserves-attest-RESERVE_PUB.h>
+#include <taler/exchange/post-reserves-attest-RESERVE_PUB.h>
+#include <taler/exchange/post-reserves-RESERVE_PUB-close.h>
+#include <taler/exchange/get-reserves-RESERVE_PUB.h>
+#include <taler/exchange/get-aml-OFFICER_PUB-legitimizations.h>
#include \
<taler/exchange/get-aml-OFFICER_PUB-attributes-H_NORMALIZED_PAYTO.h>
-#include <taler/exchange/get-aml-OFFICER_PUB-transfers-credit.h> /* UNNECESSARY? */
-#include <taler/exchange/get-aml-OFFICER_PUB-decisions.h> /* UNNECESSARY? */
+#include <taler/exchange/get-aml-OFFICER_PUB-transfers-credit.h>
+#include <taler/exchange/get-aml-OFFICER_PUB-decisions.h>
#endif /* _TALER_EXCHANGE_SERVICE_H */
diff --git a/src/lib/exchange_api_post-kyc-upload-ID.c b/src/lib/exchange_api_post-kyc-upload-ID.c
@@ -0,0 +1,247 @@
+/*
+ This file is part of TALER
+ Copyright (C) 2024-2026 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 lib/exchange_api_post-kyc-upload-ID.c
+ * @brief functions to upload client-provided KYC evidence
+ * @author Christian Grothoff
+ */
+#include "taler/taler_json_lib.h"
+#include <microhttpd.h>
+#include <gnunet/gnunet_curl_lib.h>
+#include "taler/exchange/post-kyc-upload-ID.h"
+#include "exchange_api_curl_defaults.h"
+#include "taler/taler_signatures.h"
+#include "taler/taler_curl_lib.h"
+
+
+struct TALER_EXCHANGE_PostKycUploadHandle
+{
+
+ /**
+ * The base URL for this request.
+ */
+ char *base_url;
+
+ /**
+ * The full URL for this request.
+ */
+ char *url;
+
+ /**
+ * Minor context that holds body and headers.
+ */
+ struct TALER_CURL_PostContext post_ctx;
+
+ /**
+ * Handle for the request.
+ */
+ struct GNUNET_CURL_Job *job;
+
+ /**
+ * Function to call with the result.
+ */
+ TALER_EXCHANGE_PostKycUploadCallback cb;
+
+ /**
+ * Closure for @e cb.
+ */
+ TALER_EXCHANGE_POST_KYC_UPLOAD_RESULT_CLOSURE *cb_cls;
+
+ /**
+ * Reference to the execution context.
+ */
+ struct GNUNET_CURL_Context *ctx;
+
+ /**
+ * Identifier for the KYC process the upload is for.
+ */
+ char *id;
+
+ /**
+ * Client-provided evidence to upload (`CustomerKycAttributes`).
+ */
+ json_t *attributes;
+
+};
+
+
+/**
+ * Function called when we're done processing the
+ * HTTP POST /kyc-upload/$ID request.
+ *
+ * @param cls the `struct TALER_EXCHANGE_PostKycUploadHandle *`
+ * @param response_code HTTP response code, 0 on error
+ * @param response response body, NULL if not in JSON
+ */
+static void
+handle_kyc_upload_finished (void *cls,
+ long response_code,
+ const void *response)
+{
+ struct TALER_EXCHANGE_PostKycUploadHandle *pksh = cls;
+ const json_t *json = response;
+ struct TALER_EXCHANGE_PostKycUploadResponse adr = {
+ .hr.http_status = (unsigned int) response_code,
+ .hr.reply = json
+ };
+
+ pksh->job = NULL;
+ switch (response_code)
+ {
+ case 0:
+ /* no reply */
+ adr.hr.ec = TALER_EC_GENERIC_INVALID_RESPONSE;
+ adr.hr.hint = "server offline?";
+ break;
+ case MHD_HTTP_NO_CONTENT:
+ /* success, nothing to parse */
+ break;
+ case MHD_HTTP_BAD_REQUEST:
+ adr.hr.ec = TALER_JSON_get_error_code (json);
+ adr.hr.hint = TALER_JSON_get_error_hint (json);
+ break;
+ case MHD_HTTP_NOT_FOUND:
+ adr.hr.ec = TALER_JSON_get_error_code (json);
+ adr.hr.hint = TALER_JSON_get_error_hint (json);
+ break;
+ case MHD_HTTP_CONFLICT:
+ adr.hr.ec = TALER_JSON_get_error_code (json);
+ adr.hr.hint = TALER_JSON_get_error_hint (json);
+ break;
+ case MHD_HTTP_CONTENT_TOO_LARGE:
+ adr.hr.ec = TALER_JSON_get_error_code (json);
+ adr.hr.hint = TALER_JSON_get_error_hint (json);
+ break;
+ case MHD_HTTP_INTERNAL_SERVER_ERROR:
+ adr.hr.ec = TALER_JSON_get_error_code (json);
+ adr.hr.hint = TALER_JSON_get_error_hint (json);
+ break;
+ default:
+ /* unexpected response code */
+ GNUNET_break_op (0);
+ adr.hr.ec = TALER_JSON_get_error_code (json);
+ adr.hr.hint = TALER_JSON_get_error_hint (json);
+ GNUNET_log (GNUNET_ERROR_TYPE_ERROR,
+ "Unexpected response code %u/%d for exchange POST kyc-upload\n",
+ (unsigned int) response_code,
+ (int) adr.hr.ec);
+ break;
+ }
+ if (NULL != pksh->cb)
+ {
+ pksh->cb (pksh->cb_cls,
+ &adr);
+ pksh->cb = NULL;
+ }
+ TALER_EXCHANGE_post_kyc_upload_cancel (pksh);
+}
+
+
+struct TALER_EXCHANGE_PostKycUploadHandle *
+TALER_EXCHANGE_post_kyc_upload_create (
+ struct GNUNET_CURL_Context *ctx,
+ const char *url,
+ const char *id,
+ const json_t *attributes)
+{
+ struct TALER_EXCHANGE_PostKycUploadHandle *pksh;
+
+ pksh = GNUNET_new (struct TALER_EXCHANGE_PostKycUploadHandle);
+ pksh->ctx = ctx;
+ pksh->base_url = GNUNET_strdup (url);
+ pksh->id = GNUNET_strdup (id);
+ pksh->attributes = json_incref ((json_t *) attributes);
+ return pksh;
+}
+
+
+enum TALER_ErrorCode
+TALER_EXCHANGE_post_kyc_upload_start (
+ struct TALER_EXCHANGE_PostKycUploadHandle *pksh,
+ TALER_EXCHANGE_PostKycUploadCallback cb,
+ TALER_EXCHANGE_POST_KYC_UPLOAD_RESULT_CLOSURE *cb_cls)
+{
+ CURL *eh;
+ char *path;
+
+ pksh->cb = cb;
+ pksh->cb_cls = cb_cls;
+ GNUNET_asprintf (&path,
+ "kyc-upload/%s",
+ pksh->id);
+ pksh->url = TALER_url_join (pksh->base_url,
+ path,
+ NULL);
+ GNUNET_free (path);
+ if (NULL == pksh->url)
+ {
+ GNUNET_log (GNUNET_ERROR_TYPE_ERROR,
+ "Could not construct request URL.\n");
+ return TALER_EC_GENERIC_CONFIGURATION_INVALID;
+ }
+ eh = TALER_EXCHANGE_curl_easy_get_ (pksh->url);
+ if ( (NULL == eh) ||
+ (GNUNET_OK !=
+ TALER_curl_easy_post (&pksh->post_ctx,
+ eh,
+ pksh->attributes)) )
+ {
+ GNUNET_break (0);
+ if (NULL != eh)
+ curl_easy_cleanup (eh);
+ GNUNET_free (pksh->url);
+ pksh->url = NULL;
+ return TALER_EC_GENERIC_INTERNAL_INVARIANT_FAILURE;
+ }
+ GNUNET_log (GNUNET_ERROR_TYPE_DEBUG,
+ "Requesting URL '%s'\n",
+ pksh->url);
+ pksh->job = GNUNET_CURL_job_add2 (pksh->ctx,
+ eh,
+ pksh->post_ctx.headers,
+ &handle_kyc_upload_finished,
+ pksh);
+ if (NULL == pksh->job)
+ {
+ TALER_curl_easy_post_finished (&pksh->post_ctx);
+ GNUNET_free (pksh->url);
+ pksh->url = NULL;
+ return TALER_EC_GENERIC_INTERNAL_INVARIANT_FAILURE;
+ }
+ return TALER_EC_NONE;
+}
+
+
+void
+TALER_EXCHANGE_post_kyc_upload_cancel (
+ struct TALER_EXCHANGE_PostKycUploadHandle *pksh)
+{
+ if (NULL != pksh->job)
+ {
+ GNUNET_CURL_job_cancel (pksh->job);
+ pksh->job = NULL;
+ }
+ TALER_curl_easy_post_finished (&pksh->post_ctx);
+ json_decref (pksh->attributes);
+ GNUNET_free (pksh->url);
+ GNUNET_free (pksh->base_url);
+ GNUNET_free (pksh->id);
+ GNUNET_free (pksh);
+}
+
+
+/* end of exchange_api_post-kyc-upload-ID.c */
diff --git a/src/lib/meson.build b/src/lib/meson.build
@@ -31,6 +31,7 @@ libtalerexchange_la_SOURCES = [
'exchange_api_post-blinding-prepare.c',
'exchange_api_post-coins-COIN_PUB-refund.c',
'exchange_api_post-kyc-start-ID.c',
+ 'exchange_api_post-kyc-upload-ID.c',
'exchange_api_post-kyc-wallet.c',
'exchange_api_post-management-aml-officers.c',
'exchange_api_post-management-auditors-AUDITOR_PUB-disable.c',
