merchant

taler-merchant-httpd_post-private-orders-ORDER_ID-collect.c (14925B)

---

 /*
   This file is part of TALER
   (C) 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 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 src/backend/taler-merchant-httpd_post-private-orders-ORDER_ID-collect.c
  * @brief Handle request to collect a zero-Taler order without a wallet
  * @author Bohdan Potuzhnyi
  * @author Volodymyr Potuzhnyi
  */
 #include "platform.h"
 #include <jansson.h>
 #include <taler/taler_json_lib.h>
 #include <taler/taler_merchant_util.h>
 #include "taler-merchant-httpd_post-private-orders-ORDER_ID-collect.h"
 #include "taler-merchant-httpd_post-orders-ORDER_ID-claim.h"
 #include "taler-merchant-httpd_post-orders-ORDER_ID-pay.h"
 #include "merchant-database/get_contract_terms.h"
 #include "merchant-database/get_order.h"
 #include "merchant-database/preflight.h"
 
 
 /**
  * Outcome of checking whether an order may be collected.
  */
 enum CollectCheck
 {
 
   /**
    * The contract terms could not be parsed, or use a contract version
    * we do not know.  This is about the contract we stored ourselves,
    * so it indicates a problem on our side, not a bad request.
    */
   COLLECT_CHECK_INVALID = 0,
 
   /**
    * The order can be collected: nothing remains to be paid with
    * coins, so the payment logic will find an empty balance to settle.
    */
   COLLECT_CHECK_OK,
 
   /**
    * The order is not free on the Taler side, so completing it needs a
    * wallet and the merchant must not do it on the customer's behalf.
    * "Free" here means all of: the amount to be paid over Taler is
    * zero (the rest being covered by @e amount_external), the choice
    * consumes no token @e inputs, and it yields no token @e outputs.
    */
   COLLECT_CHECK_NOT_FREE,
 
   /**
    * The contract is v1 and thus offers several choices, but the
    * client did not say which one to collect.  We do not pick one on
    * the client's behalf, just as the backend does not pick one on the
    * wallet's behalf when paying normally.
    */
   COLLECT_CHECK_CHOICE_MISSING,
 
   /**
    * A choice was given that the contract does not offer: either an
    * index beyond the end of the v1 @e choices array, or any index at
    * all for a v0 contract, which has no choices to select from.
    */
   COLLECT_CHECK_CHOICE_OUT_OF_BOUNDS
 
 };
 
 
 /**
  * How often do we retry the database transaction?
  */
 #define MAX_RETRIES 3
 
 
 /**
  * Derive the deterministic nonce this backend uses to claim
  * @a order_id itself. Using a deterministic nonce allows us to
  * distinguish orders we claimed via collect from orders claimed
  * by a customer wallet, and makes the collect operation
  * idempotent.
  *
  * @param hc handler context with the instance public key
  * @param order_id order the nonce is for
  * @param[out] nonce set to the derived nonce
  */
 static void
 derive_collect_nonce (const struct TMH_HandlerContext *hc,
                       const char *order_id,
                       struct GNUNET_CRYPTO_EddsaPublicKey *nonce)
 {
   GNUNET_assert (GNUNET_YES ==
                  GNUNET_CRYPTO_hkdf_gnunet (
                    nonce,
                    sizeof (*nonce),
                    order_id,
                    strlen (order_id),
                    &hc->instance->merchant_pub,
                    sizeof (hc->instance->merchant_pub)));
 }
 
 
 /**
  * Check that @a contract_terms describe an order the backend may
  * complete on its own: a genuinely free Taler payment.
  *
  * The payment logic we hand the order to assumes it is paid with
  * coins; handing it an order that actually costs something would make
  * it fail in a way that says nothing useful, so we filter those out
  * before claiming anything.
  *
  * @param contract_terms contract terms to check
  * @param choice_index choice selected by the client, -1 if none was given
  * @return #COLLECT_CHECK_OK if the order can be collected
  */
 static enum CollectCheck
 check_collectable (const json_t *contract_terms,
                    int16_t choice_index)
 {
   enum TALER_MERCHANT_ContractVersion version
     = TALER_MERCHANT_CONTRACT_VERSION_0;
   struct GNUNET_JSON_Specification spec[] = {
     GNUNET_JSON_spec_mark_optional (
       TALER_MERCHANT_spec_contract_version ("version",
                                             &version),
       NULL),
     GNUNET_JSON_spec_end ()
   };
 
   if (GNUNET_OK !=
       GNUNET_JSON_parse (contract_terms,
                          spec,
                          NULL,
                          NULL))
   {
     GNUNET_break (0);
     return COLLECT_CHECK_INVALID;
   }
   switch (version)
   {
   case TALER_MERCHANT_CONTRACT_VERSION_0:
     {
       struct TALER_Amount amount;
       struct GNUNET_JSON_Specification aspec[] = {
         TALER_JSON_spec_amount_any ("amount",
                                     &amount),
         GNUNET_JSON_spec_end ()
       };
 
       if (GNUNET_OK !=
           GNUNET_JSON_parse (contract_terms,
                              aspec,
                              NULL,
                              NULL))
       {
         GNUNET_break (0);
         return COLLECT_CHECK_INVALID;
       }
       if (0 <= choice_index)
       {
         /* v0 contracts have no choices to select from */
         GNUNET_break_op (0);
         return COLLECT_CHECK_CHOICE_OUT_OF_BOUNDS;
       }
       if (! TALER_amount_is_zero (&amount))
         return COLLECT_CHECK_NOT_FREE;
       return COLLECT_CHECK_OK;
     }
   case TALER_MERCHANT_CONTRACT_VERSION_1:
     {
       const json_t *choice;
       struct TALER_Amount amount;
 
       if (0 > choice_index)
       {
         /* Which choice to complete is the client's decision, just as
            it is the wallet's decision when paying normally. */
         GNUNET_break_op (0);
         return COLLECT_CHECK_CHOICE_MISSING;
       }
       choice = json_array_get (json_object_get (contract_terms,
                                                 "choices"),
                                (size_t) choice_index);
       if (NULL == choice)
       {
         GNUNET_break_op (0);
         return COLLECT_CHECK_CHOICE_OUT_OF_BOUNDS;
       }
       {
         struct GNUNET_JSON_Specification cspec[] = {
           TALER_JSON_spec_amount_any ("amount",
                                       &amount),
           GNUNET_JSON_spec_end ()
         };
 
         if (GNUNET_OK !=
             GNUNET_JSON_parse (choice,
                                cspec,
                                NULL,
                                NULL))
         {
           GNUNET_break (0);
           return COLLECT_CHECK_INVALID;
         }
       }
       if (! TALER_amount_is_zero (&amount))
         return COLLECT_CHECK_NOT_FREE;
       if (0 != json_array_size (json_object_get (choice,
                                                  "inputs")))
         return COLLECT_CHECK_NOT_FREE;
       if (0 != json_array_size (json_object_get (choice,
                                                  "outputs")))
         return COLLECT_CHECK_NOT_FREE;
       return COLLECT_CHECK_OK;
     }
   }
   GNUNET_break (0);
   return COLLECT_CHECK_INVALID;
 }
 
 
 enum MHD_Result
 TMH_private_post_orders_ID_collect (const struct TMH_RequestHandler *rh,
                                     struct MHD_Connection *connection,
                                     struct TMH_HandlerContext *hc)
 {
   const char *order_id = hc->infix;
   const char *session_id = NULL;
   int16_t choice_index = -1;
   struct GNUNET_CRYPTO_EddsaPublicKey nonce;
   struct TALER_ClaimTokenP order_ct = { 0 };
   json_t *contract_terms = NULL;
   enum GNUNET_DB_QueryStatus qs;
 
   if (NULL != hc->ctx)
   {
     /* We already handed this request over to the payment logic and
        were resumed; let it continue where it left off. */
     return TMH_post_orders_ID_pay (rh,
                                    connection,
                                    hc);
   }
   if (NULL != hc->request_body)
   {
     struct GNUNET_JSON_Specification spec[] = {
       GNUNET_JSON_spec_mark_optional (
         GNUNET_JSON_spec_string ("session_id",
                                  &session_id),
         NULL),
       GNUNET_JSON_spec_mark_optional (
         GNUNET_JSON_spec_int16 ("choice_index",
                                 &choice_index),
         NULL),
       GNUNET_JSON_spec_end ()
     };
     enum GNUNET_GenericReturnValue res;
 
     res = TALER_MHD_parse_json_data (connection,
                                      hc->request_body,
                                      spec);
     if (GNUNET_OK != res)
     {
       GNUNET_break_op (0);
       return (GNUNET_NO == res)
              ? MHD_YES
              : MHD_NO;
     }
   }
 
   /* Pre-filter: only genuinely free orders may be completed without a
      wallet, and the client has to say which choice to complete. */
   {
     json_t *order_terms = NULL;
     uint64_t order_serial;
 
     TALER_MERCHANTDB_preflight (TMH_db);
     qs = TALER_MERCHANTDB_get_contract_terms (TMH_db,
                                               hc->instance->settings.id,
                                               order_id,
                                               &order_terms,
                                               &order_serial,
                                               NULL);
     if (GNUNET_DB_STATUS_SUCCESS_NO_RESULTS == qs)
     {
       struct TALER_MerchantPostDataHashP unused;
 
       /* Remember the order's own claim token: as the merchant we may
          present it ourselves when claiming the order below. */
       qs = TALER_MERCHANTDB_get_order (TMH_db,
                                        hc->instance->settings.id,
                                        order_id,
                                        &order_ct,
                                        &unused,
                                        &order_terms);
     }
     if (0 > qs)
       return TALER_MHD_reply_with_error (connection,
                                          MHD_HTTP_INTERNAL_SERVER_ERROR,
                                          TALER_EC_GENERIC_DB_FETCH_FAILED,
                                          "get order for collection");
     if (GNUNET_DB_STATUS_SUCCESS_NO_RESULTS == qs)
       return TALER_MHD_reply_with_error (connection,
                                          MHD_HTTP_NOT_FOUND,
                                          TALER_EC_MERCHANT_GENERIC_ORDER_UNKNOWN,
                                          order_id);
     {
       enum CollectCheck cc;
 
       cc = check_collectable (order_terms,
                               choice_index);
       json_decref (order_terms);
       switch (cc)
       {
       case COLLECT_CHECK_OK:
         break;
       case COLLECT_CHECK_NOT_FREE:
         return TALER_MHD_reply_with_error (
           connection,
           MHD_HTTP_CONFLICT,
           TALER_EC_MERCHANT_PRIVATE_POST_ORDERS_ID_COLLECT_NOT_FREE,
           order_id);
       case COLLECT_CHECK_CHOICE_MISSING:
         return TALER_MHD_reply_with_error (
           connection,
           MHD_HTTP_BAD_REQUEST,
           TALER_EC_MERCHANT_POST_ORDERS_ID_PAY_CHOICE_INDEX_MISSING,
           order_id);
       case COLLECT_CHECK_CHOICE_OUT_OF_BOUNDS:
         return TALER_MHD_reply_with_error (
           connection,
           MHD_HTTP_BAD_REQUEST,
           TALER_EC_MERCHANT_POST_ORDERS_ID_PAY_CHOICE_INDEX_OUT_OF_BOUNDS,
           order_id);
       case COLLECT_CHECK_INVALID:
         return TALER_MHD_reply_with_error (
           connection,
           MHD_HTTP_INTERNAL_SERVER_ERROR,
           TALER_EC_MERCHANT_GENERIC_DB_CONTRACT_CONTENT_INVALID,
           order_id);
       }
     }
   }
 
   /* Claim the order for ourselves */
   derive_collect_nonce (hc,
                         order_id,
                         &nonce);
   for (unsigned int i=0; i<MAX_RETRIES; i++)
   {
     TALER_MERCHANTDB_preflight (TMH_db);
     qs = TMH_claim_order (hc,
                           order_id,
                           &nonce,
                           &order_ct,
                           &contract_terms);
     if (GNUNET_DB_STATUS_SOFT_ERROR != qs)
       break;
   }
   switch (qs)
   {
   case GNUNET_DB_STATUS_HARD_ERROR:
     return TALER_MHD_reply_with_error (connection,
                                        MHD_HTTP_INTERNAL_SERVER_ERROR,
                                        TALER_EC_GENERIC_DB_COMMIT_FAILED,
                                        NULL);
   case GNUNET_DB_STATUS_SOFT_ERROR:
     return TALER_MHD_reply_with_error (connection,
                                        MHD_HTTP_INTERNAL_SERVER_ERROR,
                                        TALER_EC_GENERIC_DB_SOFT_FAILURE,
                                        NULL);
   case GNUNET_DB_STATUS_SUCCESS_NO_RESULTS:
     if (NULL == contract_terms)
       return TALER_MHD_reply_with_error (connection,
                                          MHD_HTTP_NOT_FOUND,
                                          TALER_EC_MERCHANT_GENERIC_ORDER_UNKNOWN,
                                          order_id);
     /* Claimed by a customer wallet: the wallet owns the order and has
        to execute the payment itself. */
     json_decref (contract_terms);
     return TALER_MHD_reply_with_error (
       connection,
       MHD_HTTP_CONFLICT,
       TALER_EC_MERCHANT_PRIVATE_POST_ORDERS_ID_COLLECT_ALREADY_CLAIMED,
       order_id);
   case GNUNET_DB_STATUS_SUCCESS_ONE_RESULT:
     GNUNET_assert (NULL != contract_terms);
     json_decref (contract_terms);
     break;
   }
 
   /* Turn our request into the payment request a wallet would send for
      a free order and let the regular payment logic handle it, so that
      collecting an order behaves exactly like paying it. */
   {
     json_t *pay_request;
 
     pay_request = GNUNET_JSON_PACK (
       GNUNET_JSON_pack_array_steal ("coins",
                                     json_array ()),
       GNUNET_JSON_pack_allow_null (
         GNUNET_JSON_pack_string ("session_id",
                                  session_id)));
     GNUNET_assert (NULL != pay_request);
     if (0 <= choice_index)
       GNUNET_assert (0 ==
                      json_object_set_new (
                        pay_request,
                        "wallet_data",
                        GNUNET_JSON_PACK (
                          GNUNET_JSON_pack_int64 ("choice_index",
                                                  choice_index))));
     if (NULL != hc->request_body)
       json_decref (hc->request_body);
     hc->request_body = pay_request;
   }
   return TMH_post_orders_ID_pay (rh,
                                  connection,
                                  hc);
 }
 
 
 /* end of taler-merchant-httpd_post-private-orders-ORDER_ID-collect.c */