get-aml-OFFICER_PUB-measures.rst (5336B)
1 .. http:get:: /aml/$OFFICER_PUB/measures 2 3 To enable the AML staff SPA to give AML staff a choice of possible measures, a 4 new endpoint ``/aml/$OFFICER_PUB/measures`` is added that allows the AML SPA 5 to dynamically GET the list of available measures. It returns a list of known 6 KYC checks (by name) with their descriptions and a list of AML programs with 7 information about the required context. 8 9 This endpoint was introduced in protocol **v20**. 10 11 **Request:** 12 13 *Taler-AML-Officer-Signature*: 14 The client must provide Base-32 encoded EdDSA signature with 15 ``$OFFICER_PRIV``, affirming the desire to obtain AML data. Note that 16 this is merely a simple authentication mechanism, the details of the 17 request are not protected by the signature. 18 19 **Response:** 20 21 :http:statuscode:`200 Ok`: 22 Information about possible measures is returned in a 23 `AvailableMeasureSummary` object. 24 :http:statuscode:`400 Bad Request`: 25 The request is malformed. Cases include: 26 27 - The ``$H_OFFICER_PUB`` path segment is malformed. 28 This response comes with a standard `ErrorDetail` response with 29 a code of ``TALER_EC_GENERIC_PATH_SEGMENT_MALFORMED``. 30 - The required HTTP header with the signature is missing. Returned with 31 ``TALER_EC_GENERIC_HTTP_HEADERS_MALFORMED``. 32 33 :http:statuscode:`403 Forbidden`: 34 Two cases: 35 36 - The signature is invalid. Returned with a code of 37 ``TALER_EC_EXCHANGE_GENERIC_AML_OFFICER_GET_SIGNATURE_INVALID``. 38 - The specific officer is unknown or disabled. Returned with a code of 39 ``TALER_EC_EXCHANGE_GENERIC_AML_OFFICER_ACCESS_DENIED``. 40 41 :http:statuscode:`500 Internal server error`: 42 The server had an internal problem handling the request. 43 The error code is usually a ``TALER_EC_GENERIC_DB_FETCH_FAILED``. 44 45 46 **Details:** 47 48 .. ts:def:: AvailableMeasureSummary 49 50 interface AvailableMeasureSummary { 51 52 // Available original measures that can be 53 // triggered directly by default rules. 54 roots: { "$measure_name" : MeasureInformation; }; 55 56 // Available AML programs. 57 programs: { "$prog_name" : AmlProgramRequirement; }; 58 59 // Available KYC checks. 60 checks: { "$check_name" : KycCheckInformation; }; 61 62 // Default KYC rules. This is the set of KYC rules that 63 // applies by default to new "accounts". Note that some 64 // rules only apply to wallets, while others only apply to 65 // bank accounts. The returned array is the union of all 66 // possible rules, applications should consider the 67 // ``operation_type`` to filter for rules that actually 68 // apply to a specific situation. 69 // @since protocol **v28**. 70 default_rules: KycRule[]; 71 72 } 73 74 .. ts:def:: MeasureInformation 75 76 interface MeasureInformation { 77 78 // Name of a KYC check. 79 check_name: string; 80 81 // Name of an AML program. 82 // Optional @since protocol **v30**. 83 prog_name?: string; 84 85 // Context for the check. Optional. 86 context?: Object; 87 88 // Operation that this measure relates to. 89 // NULL if unknown. Useful as a hint to the 90 // user if there are many (voluntary) measures 91 // and some related to unlocking certain operations. 92 // (and due to zero-amount thresholds, no measure 93 // was actually specifically triggered). 94 // 95 // Must be one of "WITHDRAW", "DEPOSIT", 96 // (p2p) "MERGE", (wallet) "BALANCE", 97 // (reserve) "CLOSE", "AGGREGATE", 98 // "TRANSACTION" or "REFUND". 99 // @since protocol **v21**. 100 operation_type?: string; 101 102 // Can this measure be undertaken voluntarily? 103 // Optional, default is false. 104 // @since protocol **vATTEST**. 105 voluntary?: boolean; 106 107 } 108 109 .. ts:def:: AmlProgramRequirement 110 111 interface AmlProgramRequirement { 112 113 // Description of what the AML program does. 114 description: string; 115 116 // List of required field names in the context to run this 117 // AML program. SPA must check that the AML staff is providing 118 // adequate CONTEXT when defining a measure using this program. 119 context: string[]; 120 121 // List of required attribute names in the 122 // input of this AML program. These attributes 123 // are the minimum that the check must produce 124 // (it may produce more). 125 inputs: string[]; 126 127 } 128 129 .. ts:def:: KycCheckInformation 130 131 interface KycCheckInformation { 132 133 // Description of the KYC check. Should be shown 134 // to the AML staff but will also be shown to the 135 // client when they initiate the check in the KYC SPA. 136 description: string; 137 138 // Map from IETF BCP 47 language tags to localized 139 // description texts. 140 description_i18n ?: { [lang_tag: string]: string}; 141 142 // Names of the fields that the CONTEXT must provide 143 // as inputs to this check. 144 // SPA must check that the AML staff is providing 145 // adequate CONTEXT when defining a measure using 146 // this check. 147 requires: string[]; 148 149 // Names of the attributes the check will output. 150 // SPA must check that the outputs match the 151 // required inputs when combining a KYC check 152 // with an AML program into a measure. 153 outputs: string[]; 154 155 // Name of a root measure taken when this check fails. 156 fallback: string; 157 }