get-aml-OFFICER_PUB-decisions.h (14071B)
1 /* 2 This file is part of TALER 3 Copyright (C) 2025, 2026 Taler Systems SA 4 5 TALER is free software; you can redistribute it and/or modify it under the 6 terms of the GNU Affero General Public License as published by the Free Software 7 Foundation; either version 3, or (at your option) any later version. 8 9 TALER is distributed in the hope that it will be useful, but WITHOUT ANY 10 WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR 11 A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details. 12 13 You should have received a copy of the GNU Affero General Public License along with 14 TALER; see the file COPYING. If not, see <http://www.gnu.org/licenses/> 15 */ 16 /** 17 * @file include/taler/taler-exchange/get-aml-OFFICER_PUB-decisions.h 18 * @brief C interface for the GET /aml/$OFFICER_PUB/decisions endpoint 19 * @author Christian Grothoff 20 */ 21 #ifndef _TALER_EXCHANGE__GET_AML_OFFICER_PUB_DECISIONS_H 22 #define _TALER_EXCHANGE__GET_AML_OFFICER_PUB_DECISIONS_H 23 24 #include <taler/taler-exchange/common.h> 25 26 /** 27 * Possible options we can set for the GET decisions request. 28 */ 29 enum TALER_EXCHANGE_GetAmlDecisionsOption 30 { 31 /** 32 * End of list of options. 33 */ 34 TALER_EXCHANGE_GET_AML_DECISIONS_OPTION_END = 0, 35 36 /** 37 * Return at most N values, default is -20 to return 38 * the last 20 entries before start. Negative values 39 * to return before limit, positive to return after limit. 40 */ 41 TALER_EXCHANGE_GET_AML_DECISIONS_OPTION_LIMIT, 42 43 /** 44 * Row number threshold, defaults to INT64_MAX, namely 45 * the biggest row id possible in the database. 46 */ 47 TALER_EXCHANGE_GET_AML_DECISIONS_OPTION_OFFSET, 48 49 /** 50 * Filter by account using a normalized payto URI hash. 51 */ 52 TALER_EXCHANGE_GET_AML_DECISIONS_OPTION_H_PAYTO, 53 54 /** 55 * If set to #TALER_EXCHANGE_YNA_YES, only return active 56 * results, #TALER_EXCHANGE_YNA_NO, only return inactive 57 * results, #TALER_EXCHANGE_YNA_ALL, to return all 58 * decisions. Default is all. 59 */ 60 TALER_EXCHANGE_GET_AML_DECISIONS_OPTION_ACTIVE, 61 62 /** 63 * If set to #TALER_EXCHANGE_YNA_YES, only return accounts 64 * under investigation, #TALER_EXCHANGE_YNA_NO, only return 65 * accounts not under investigation, #TALER_EXCHANGE_YNA_ALL, 66 * to return all accounts. Default is all. 67 */ 68 TALER_EXCHANGE_GET_AML_DECISIONS_OPTION_INVESTIGATION 69 70 }; 71 72 73 /** 74 * Possible options we can set for the GET decisions request. 75 */ 76 struct TALER_EXCHANGE_GetAmlDecisionsOptionValue 77 { 78 79 /** 80 * Type of the option being set. 81 */ 82 enum TALER_EXCHANGE_GetAmlDecisionsOption option; 83 84 /** 85 * Specific option value. 86 */ 87 union 88 { 89 90 /** 91 * Value of if @e option is TALER_EXCHANGE_GET_AML_DECISIONS_OPTION_LIMIT. 92 */ 93 int64_t limit; 94 95 /** 96 * Value of if @e option is TALER_EXCHANGE_GET_AML_DECISIONS_OPTION_OFFSET. 97 * Note that in practice the maximum value is INT64_MAX, even though 98 * this value is unsigned. 99 */ 100 uint64_t offset; 101 102 /** 103 * Value of if @e option is TALER_EXCHANGE_GET_AML_DECISIONS_OPTION_H_PAYTO. 104 */ 105 const struct TALER_NormalizedPaytoHashP *h_payto; 106 107 /** 108 * Value of if @e option is TALER_EXCHANGE_GET_AML_DECISIONS_OPTION_ACTIVE. 109 */ 110 enum TALER_EXCHANGE_YesNoAll active; 111 112 /** 113 * Value of if @e option is TALER_EXCHANGE_GET_AML_DECISIONS_OPTION_INVESTIGATION. 114 */ 115 enum TALER_EXCHANGE_YesNoAll investigation; 116 117 } details; 118 119 }; 120 121 122 /** 123 * Handle for an operation to GET /aml/$OFFICER_PUB/decisions. 124 */ 125 struct TALER_EXCHANGE_GetAmlDecisionsHandle; 126 127 128 /** 129 * Information about a KYC rule. 130 */ 131 struct TALER_EXCHANGE_GetAmlDecisionsKycRule 132 { 133 /** 134 * Type of operation to which the rule applies. 135 */ 136 enum TALER_KYCLOGIC_KycTriggerEvent operation_type; 137 138 /** 139 * Name of the configuration section this rule originates from. 140 * Can be NULL. 141 */ 142 const char *rule_name; 143 144 /** 145 * The threshold amount that triggers the measures. 146 */ 147 struct TALER_Amount threshold; 148 149 /** 150 * Over which duration should the threshold be computed. 151 */ 152 struct GNUNET_TIME_Relative timeframe; 153 154 /** 155 * Length of the @e measures array. 156 */ 157 size_t measures_length; 158 159 /** 160 * Array of names of measures to apply. 161 */ 162 const char **measures; 163 164 /** 165 * Display priority for this rule. 166 */ 167 int64_t display_priority; 168 169 /** 170 * True if the rule should be exposed to the client. 171 */ 172 bool exposed; 173 174 /** 175 * True if all measures need to be satisfied (AND combinator), 176 * false if any measure is sufficient (OR combinator). 177 */ 178 bool is_and_combinator; 179 }; 180 181 182 /** 183 * Legitimization rule set associated with an AML decision. 184 */ 185 struct TALER_EXCHANGE_GetAmlDecisionsLegitimizationRuleSet 186 { 187 /** 188 * When does this set of rules expire? 189 */ 190 struct GNUNET_TIME_Timestamp expiration_time; 191 192 /** 193 * Name of the successor measure to apply when expiration time is reached. 194 * Can be NULL. 195 */ 196 const char *successor_measure; 197 198 /** 199 * Length of the @e rules array. 200 */ 201 size_t rules_length; 202 203 /** 204 * Array of KYC rules. NOT allocated here! 205 */ 206 const struct TALER_EXCHANGE_GetAmlDecisionsKycRule *rules; 207 208 /** 209 * Custom measures. 210 */ 211 const json_t *custom_measures; 212 }; 213 214 215 /** 216 * Entry in the set of AML decisions that are returned 217 * by the server in a single request. 218 */ 219 struct TALER_EXCHANGE_GetAmlDecisionsDecision 220 { 221 /** 222 * Hash of the normalized payto:// URI of the account the 223 * decision applies to. 224 */ 225 struct TALER_NormalizedPaytoHashP h_payto; 226 227 /** 228 * Full payto:// URI of the account the decision applies to. 229 * Since protocol v30 (rev 1). 230 */ 231 const char *full_payto; 232 233 /** 234 * True if the underlying payto://-URI is for a wallet. 235 */ 236 bool is_wallet; 237 238 /** 239 * Row ID of the decision in the exchange database. 240 */ 241 uint64_t rowid; 242 243 /** 244 * Justification for the decision. Can be NULL. 245 */ 246 const char *justification; 247 248 /** 249 * When was the decision made? 250 */ 251 struct GNUNET_TIME_Timestamp decision_time; 252 253 /** 254 * Account properties. Can be NULL if no properties are set. 255 */ 256 const json_t *properties; 257 258 /** 259 * Legitimization rules that apply to this account. 260 */ 261 struct TALER_EXCHANGE_GetAmlDecisionsLegitimizationRuleSet limits; 262 263 /** 264 * True if the account is under investigation by AML staff. 265 */ 266 bool to_investigate; 267 268 /** 269 * True if this is the active decision for the account. 270 */ 271 bool is_active; 272 }; 273 274 275 /** 276 * Information returned from the exchange for a 277 * GET /aml/$OFFICER_PUB/decisions request. 278 */ 279 struct TALER_EXCHANGE_GetAmlDecisionsResponse 280 { 281 /** 282 * HTTP response data 283 */ 284 struct TALER_EXCHANGE_HttpResponse hr; 285 286 /** 287 * Details depending on the HTTP status code. 288 */ 289 union 290 { 291 292 /** 293 * Details on #MHD_HTTP_OK. 294 */ 295 struct 296 { 297 /** 298 * Length of the @e records array. 299 */ 300 size_t records_length; 301 302 /** 303 * AML decisions. 304 */ 305 const struct TALER_EXCHANGE_GetAmlDecisionsDecision *records; 306 307 } ok; 308 309 } details; 310 }; 311 312 313 /** 314 * Set up GET /aml/$OPUB/decisions operation. 315 * Note that you must explicitly start the operation after 316 * possibly setting options. 317 * 318 * @param ctx the context 319 * @param url base URL of the exchange 320 * @param officer_priv private key of the officer 321 * @return handle to operation 322 */ 323 struct TALER_EXCHANGE_GetAmlDecisionsHandle * 324 TALER_EXCHANGE_get_aml_decisions_create ( 325 struct GNUNET_CURL_Context *ctx, 326 const char *url, 327 const struct TALER_AmlOfficerPrivateKeyP *officer_priv); 328 329 330 /** 331 * Terminate the list of the options. 332 * 333 * @return the terminating object of struct TALER_EXCHANGE_GetAmlDecisionsOptionValue 334 */ 335 #define TALER_EXCHANGE_get_aml_decisions_option_end_() \ 336 (const struct TALER_EXCHANGE_GetAmlDecisionsOptionValue) \ 337 { \ 338 .option = TALER_EXCHANGE_GET_AML_DECISIONS_OPTION_END \ 339 } 340 341 /** 342 * Set limit @a l on the number of results to return. 343 * 344 * @param l limit on the number of results to return 345 * @return representation of the option as a struct TALER_EXCHANGE_GetAmlDecisionsOptionValue 346 */ 347 #define TALER_EXCHANGE_get_aml_decisions_option_limit(l) \ 348 (const struct TALER_EXCHANGE_GetAmlDecisionsOptionValue) \ 349 { \ 350 .option = TALER_EXCHANGE_GET_AML_DECISIONS_OPTION_LIMIT, \ 351 .details.limit = (l) \ 352 } 353 354 355 /** 356 * Set row offset from which to return results. 357 * 358 * @param o offset to use 359 * @return representation of the option as a struct TALER_EXCHANGE_GetAmlDecisionsOptionValue 360 */ 361 #define TALER_EXCHANGE_get_aml_decisions_option_offset(o) \ 362 (const struct TALER_EXCHANGE_GetAmlDecisionsOptionValue) \ 363 { \ 364 .option = TALER_EXCHANGE_GET_AML_DECISIONS_OPTION_OFFSET, \ 365 .details.offset = (o) \ 366 } 367 368 369 /** 370 * Set filter on which account to filter AML decisions by. 371 * 372 * @param p normalized payto URI hash of the account to filter by 373 * @return representation of the option as a struct TALER_EXCHANGE_GetAmlDecisionsOptionValue 374 */ 375 #define TALER_EXCHANGE_get_aml_decisions_option_filter_h_payto(p) \ 376 (const struct TALER_EXCHANGE_GetAmlDecisionsOptionValue) \ 377 { \ 378 .option = TALER_EXCHANGE_GET_AML_DECISIONS_OPTION_H_PAYTO, \ 379 .details.h_payto = (p) \ 380 } 381 382 /** 383 * Set filter on active (or inactive) results. 384 * 385 * @param a activity filter to use 386 * @return representation of the option as a struct TALER_EXCHANGE_GetAmlDecisionsOptionValue 387 */ 388 #define TALER_EXCHANGE_get_aml_decisions_option_filter_active(a) \ 389 (const struct TALER_EXCHANGE_GetAmlDecisionsOptionValue) \ 390 { \ 391 .option = TALER_EXCHANGE_GET_AML_DECISIONS_OPTION_ACTIVE, \ 392 .details.active = (a) \ 393 } 394 395 /** 396 * Set filter on investigation status. 397 * 398 * @param i investigation filter to use 399 * @return representation of the option as a struct TALER_EXCHANGE_GetAmlDecisionsOptionValue 400 */ 401 #define TALER_EXCHANGE_get_aml_decisions_option_filter_investigation(i) \ 402 (const struct TALER_EXCHANGE_GetAmlDecisionsOptionValue) \ 403 { \ 404 .option = TALER_EXCHANGE_GET_AML_DECISIONS_OPTION_INVESTIGATION, \ 405 .details.investigation = (i) \ 406 } 407 408 409 /** 410 * Set the requested options for the operation. 411 * 412 * If any option fail other options may be or may be not applied. 413 * 414 * @param adgh the request to set the options for 415 * @param num_options length of the @a options array 416 * @param options an array of options 417 * @return #GNUNET_OK on success, 418 * #GNUNET_NO on failure, 419 * #GNUNET_SYSERR on internal error 420 */ 421 enum GNUNET_GenericReturnValue 422 TALER_EXCHANGE_get_aml_decisions_set_options_ ( 423 struct TALER_EXCHANGE_GetAmlDecisionsHandle *adgh, 424 unsigned int num_options, 425 const struct TALER_EXCHANGE_GetAmlDecisionsOptionValue options[]); 426 427 428 /** 429 * Set the requested options for the operation. 430 * 431 * If any option fail other options may be or may be not applied. 432 * 433 * It should be used with helpers that creates required options, for example: 434 * 435 * TALER_EXCHANGE_get_aml_decisions_set_options ( 436 * adgh, 437 * TALER_EXCHANGE_get_aml_decisions_option_h_payto_(&h_payto)); 438 * 439 * @param adgh the request to set the options for 440 * @param ... the list of the options, each option must be created 441 * by helpers TALER_EXCHANGE_get_aml_decisions_option_NAME(VALUE) 442 * @return #GNUNET_OK on success, 443 * #GNUNET_NO on failure, 444 * #GNUNET_SYSERR on internal error 445 */ 446 #define TALER_EXCHANGE_get_aml_decisions_set_options(adgh,...) \ 447 TALER_EXCHANGE_get_aml_decisions_set_options_ ( \ 448 adgh, \ 449 TALER_EXCHANGE_COMMON_OPTIONS_ARRAY_MAX_SIZE, \ 450 ((const struct TALER_EXCHANGE_GetAmlDecisionsOptionValue[]) \ 451 {__VA_ARGS__, TALER_EXCHANGE_get_aml_decisions_option_end_ () } \ 452 )) 453 454 455 #ifndef TALER_EXCHANGE_GET_AML_DECISIONS_RESULT_CLOSURE 456 /** 457 * Type of the closure used by 458 * the #TALER_EXCHANGE_GetAmlDecisionsCallback. 459 */ 460 #define TALER_EXCHANGE_GET_AML_DECISIONS_RESULT_CLOSURE void 461 #endif /* _TALER_EXCHANGE_GET_AML_OFFICER_PUB_DECISIONS_H */ 462 463 /** 464 * Type of the function that receives the result of a 465 * GET /aml/$OFFICER_PUB/decisions request. 466 * 467 * @param cls closure 468 * @param result result returned by the HTTP server 469 */ 470 typedef void 471 (*TALER_EXCHANGE_GetAmlDecisionsCallback)( 472 TALER_EXCHANGE_GET_AML_DECISIONS_RESULT_CLOSURE *cls, 473 const struct TALER_EXCHANGE_GetAmlDecisionsResponse *result); 474 475 476 /** 477 * Start GET /aml/$OPUB/decisions operation. 478 * 479 * @param[in,out] adgh operation to start 480 * @param cb function to call with the exchange's result 481 * @param cb_cls closure for @a cb 482 * @return status code, #TALER_EC_NONE on success 483 */ 484 enum TALER_ErrorCode 485 TALER_EXCHANGE_get_aml_decisions_start ( 486 struct TALER_EXCHANGE_GetAmlDecisionsHandle *adgh, 487 TALER_EXCHANGE_GetAmlDecisionsCallback cb, 488 TALER_EXCHANGE_GET_AML_DECISIONS_RESULT_CLOSURE *cb_cls); 489 490 491 /** 492 * Cancel GET /aml/$OPUB/decisions operation. This function 493 * must not be called by clients after the 494 * TALER_EXCHANGE_GetAmlDecisionsCallback has been invoked 495 * (as in those cases it'll be called internally by the 496 * implementation already). 497 * 498 * @param[in] adgh operation to cancel 499 */ 500 void 501 TALER_EXCHANGE_get_aml_decisions_cancel ( 502 struct TALER_EXCHANGE_GetAmlDecisionsHandle *adgh); 503 504 505 #endif /* _TALER_EXCHANGE__GET_AML_OFFICER_PUB_DECISIONS_H */