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