taler-docs

Documentation for GNU Taler components, APIs and protocols
Log | Files | Refs | README | LICENSE

023-taler-kyc.rst (74111B)


      1 DD 23: Taler KYC
      2 ################
      3 
      4 :Design status: Accepted
      5 :Implementation status: Implemented
      6 :DD shepherd: TBD
      7 :Historical contributors: Florian Dold, Christian Grothoff, Özgür Kesim
      8 :First published: 2021-09-12
      9 :Last substantive change: 2026-05-03
     10 :Implementation evidence: exchange (2024-04-22)
     11 :Normative references: :doc:`../core/api-exchange`, :doc:`../taler-kyc-manual`
     12 
     13 .. note::
     14 
     15    This is a living design rationale.  The core exchange API and KYC manual
     16    are authoritative for implemented endpoints and operations.
     17 
     18 Summary
     19 =======
     20 
     21 This document discusses the Know-your-customer (KYC) and Anti-Money Laundering
     22 (AML) processes supported by Taler.
     23 
     24 For the current wallet-core transaction states, KYC continuation data, and
     25 available actions, see :ref:`dd37-kyc` in
     26 :doc:`037-wallet-transactions-lifecycle`.
     27 
     28 
     29 Motivation
     30 ==========
     31 
     32 To legally operate, Taler has to comply with KYC/AML regulation that requires
     33 banks to identify parties involved in transactions at certain points.
     34 
     35 
     36 Requirements
     37 ============
     38 
     39 Taler needs to take *measures* based on the following primary *triggers*:
     40 
     41 * Customer withdraws money over a monthly threshold
     42 
     43   * exchange triggers KYC
     44   * key: IBAN (encoded as payto:// URI)
     45 
     46 * Wallet receives (via refunds) money resulting in a balance over a threshold
     47 
     48   * this is a client-side restriction
     49   * key: reserve (=KYC account) long term public key per wallet (encoded as payto:// URI)
     50 
     51 * Wallet receives money via P2P payments
     52 
     53   * there are two sub-cases: PUSH and PULL payments
     54   * key: reserve (=KYC account) long term public key per wallet (encoded as payto:// URI)
     55 
     56 * Merchant receives money (Q: any money, or above a monthly threshold?)
     57 
     58   * key: IBAN (encoded as payto:// URI)
     59 
     60 * Reserve is "opened" for invoicing.
     61 
     62   * key: reserve (=KYC account) long term public key per wallet (encoded as payto:// URI)
     63 
     64 * Import of new sanctions lists and triggering of measures against matches of existing
     65   customer records against the list
     66 
     67 For the different operation types, there can be both soft and hard
     68 limits. Soft limits are those that the customer may raise by providing data
     69 and passing KYC checks.  Hard limits cannot be lifted, for example because an
     70 exchange forbids crossing those limits in its terms of service for all
     71 customers.
     72 
     73 
     74 Process requirements
     75 ^^^^^^^^^^^^^^^^^^^^
     76 
     77 The key consideration here is *plausibilization*: staff needs to
     78 check that the client-provided information is plausible. As this
     79 is highly case-dependent, this cannot be automated.
     80 
     81 For the different *measures*, there are various different possible KYC/AML
     82 *checks* that could happen:
     83 
     84 * In-person validation by AML staff
     85 * Various forms to be filled by AML staff
     86 * Validation involving local authorities and post-office
     87 * Online validation, sometimes with multiple options (like KYC for multiple people):
     88 
     89   * Forms to be supplied by user (different types of ID)
     90   * Interactive video
     91   * Documents to be supplied (business register)
     92   * Address validation (e-mail or phone or postal)
     93 
     94 Additionally, the process is dynamic and conditional upon various decisions:
     95 
     96 * Individual vs. business
     97 * PEP or non-PEP
     98 * Hit on sanctions list
     99 * Type of business (trust, foundation, listed on stock market, etc.)
    100 * Need for plausibilization (via documents by user or staff research)
    101 * Periodic updates (of customer data, of sanction lists) and re-assessment
    102 
    103 There are also various *outcomes*:
    104 
    105 * normal operation (with expiration date)
    106 * normal operation but with AML staff investigating (new measure)
    107 * held, requesting customer documentation (new measure)
    108 * held, AML staff reviewing evidence for plausibilization (new measure)
    109 * automatically frozen until certain day (due to sanctions)
    110 * institutionally frozen until certain day (due to order by state authority)
    111 * operation is categorically not allowed (at least above certain limits)
    112 
    113 Outcomes may also be (partially) public, that is exposed to the client. For
    114 example, we may want to tell a wallet that it has hit a hard withdraw limit,
    115 but might succeed at withdrawing a smaller amount.
    116 
    117 The outcome of a *check* can set new rules or trigger another *measure* (the
    118 latter is conditional on reaching the expiration time of the outcome).
    119 
    120 As a result, we largely end up in a large state machine where the AML staff has
    121 serious flexibility while the user needs guidance as to the possible next moves
    122 and/or to the current state of their account (where some information must not be
    123 disclosed).
    124 
    125 
    126 Documentation requirements
    127 ^^^^^^^^^^^^^^^^^^^^^^^^^^
    128 
    129 For each account we must:
    130 
    131 * define risk-profile (902.4, 905.1)
    132 * document the specific setup, likely not just the INI file
    133 * should have some key Anti-Money-Laundering Act (AMLA)
    134   file attributes, such as:
    135 
    136   * File opened, file closed (keep data for X years afterwards!)
    137   * low-risk or high-risk business relationship
    138   * PEP status
    139   * business domain
    140   * authority notification dates (possibly multiple) with
    141     voluntary or mandatory notification classification
    142 
    143 Finally, we need to produce statistics:
    144 
    145 * There must be a page with an overview of AMLA files with opening
    146   and closing dates and an easy way to determine for any day the
    147   number of open AMLA files
    148 * Technically, we also need a list of at-risk transactions and of
    149   frozen transactions, but given that we can really only freeze
    150   on an account-basis, I think there is nothing to do here
    151 * number of incidents reported (voluntarily, required)
    152 * number of business relationships at any point in time
    153 * number of risky business relationships (PEP, etc.)
    154 * number of frozen transactions (authority vs. sanction) with start-date and end-date
    155 * start-data and end-date of relationships (data retained for X years after end of relationship)
    156 
    157 For this high-level monitoring, we need certain designated critical events to
    158 be tracked in the system statistics:
    159 
    160 * account opened
    161 * set to high risk
    162 * set to low risk
    163 * suspicious activity report filed with authority
    164 * account frozen
    165 * account unfrozen
    166 * account closed
    167 * sanction list import / update
    168 
    169 
    170 Sanction lists
    171 ^^^^^^^^^^^^^^
    172 
    173 .. note::
    174 
    175    The implementation described in the current KYC manual supersedes this
    176    historical design sketch.
    177 
    178 We need to be able to import new sanction lists (whenever they are published)
    179 and then check existing AMLA files against those lists.  Additionally, newly
    180 created AMLA files must be checked against the current list and some "measure"
    181 applied in case of a match.
    182 
    183 This will primarily require us to define an endpoint to upload a sanction list
    184 and to define a new table to track the list of sanctioned entities.  As it is
    185 expected that sanction lists will not permit fully automated determinations in
    186 all cases, an external "sanction check" program should be configured which
    187 compares records against the current list and determines the correct measure,
    188 such as no change, further manual review by AML staff, or even automatic
    189 freeze (and report) depending on how well the records match.
    190 
    191 Basically, the "sanction check" program takes the sanction list and an
    192 attribute set to compute the same kind of `AmlOutcome` that an AML program
    193 outputs given a context and an attribute set.
    194 
    195 
    196 Security requirements
    197 ^^^^^^^^^^^^^^^^^^^^^
    198 
    199 IBANs are predictable. We (probably) do not want random people to be able to
    200 initate KYC processes for other parties. Similarly, the attestation API
    201 requires us to somehow *authenticate* the user to ensure we only give out
    202 attestation data to the data subject themselves. For P2P payments and
    203 withdrawals, we have the reserve public key that is only known to the data
    204 subject and thus can be used to authenticate the client via a signature. Only
    205 pure deposits (by merchants or directly from a wallet) are a problem as the
    206 only thing we know about the receiver is the IBAN at that time, and literally
    207 any user could just deposit money into some bank account, so knowledge of the
    208 IBAN is insufficient to determine that we actually are communicating with the
    209 owner of the bank account.
    210 
    211 
    212 Further considerations
    213 ^^^^^^^^^^^^^^^^^^^^^^
    214 
    215 On top of all of this, we need to plan some *diagnostics* to determine when
    216 components fail (such as scripts or external services providing malformed
    217 results).
    218 
    219 Optionally, in the future, the solution should support fees to be paid by the
    220 user for *voluntary* KYC processes related to attestation (#7365).
    221 
    222 
    223 Proposed Solution
    224 =================
    225 
    226 The main state of an account is represented by a set of `KYC rules <KycRule>` (the
    227 `LegitimizationRuleSet`) which specify the current *rules* to apply to
    228 transactions involving the account. Rules can *exposed* to the account owner,
    229 or can be secret.  Each *rule* specifies certain *conditions* which, if met,
    230 *trigger* a set of *measures*.  After a *rule* was *triggered* and
    231 before the *outcome* of a respective *measure* has been produced (say
    232 because the user did not yet enter their data or the AML officer is still
    233 reviewing the case), the existing rules remain in force. Rules have a display
    234 priority, and if a second rule with a higher display priority is also
    235 triggered, the *measures* of the higher-priority rule become the active
    236 *measures*.  Except for the default rule set, every legitimization rule set
    237 also has an *expiration* time after which a successor *measure* (or the
    238 default rule set) is automatically triggered.
    239 
    240 For any possible *measures*, we define:
    241 
    242 * Contextual input data to be provided (with dynamic inputs,
    243   e.g. amount set dynamically based on the *trigger* could be
    244   in the context)
    245 * A *check* to be performed (checks can be user-interactive (LINK, FORM)
    246   or staff-interactive (INFO))
    247 * A fallback *measure* to take on failure of a user-interactive check
    248   (if the check fails, we cannot run the AML *program* as required inputs
    249   might be missing!)
    250 * An (AML) *program* that uses *attribtes* from the *check* as well as
    251   *context* data to determine an *outcome* represented as the
    252   `AmlOutcome`.
    253 
    254 "verboten" is the name of a special *measure*, which means that crossing the
    255 respective transaction threshold is categorically not allowed (for this
    256 account).  "verboten" with a threshold of zero can be used to freeze funds.
    257 
    258 Possible *outcomes* of a measure include:
    259 
    260 * The next operational state (normal, AML investigation) of the account
    261   (basically, whether to add it to the work list of AML staff).
    262 * A new set of *rules* in the form of a `LegitimizationRuleSet` that
    263   determines custom rules to apply to transactions involving the account;
    264   such rules may be used to block certain transactions by using the
    265   "verboten" measure.  The `LegitimizationRuleSet` also must specify
    266   an *expiration* time by which we fall back to a successor measure
    267   *or* to the default rules.
    268 * A (largely) free-form set of `AccountProperties` that AML staff can
    269   use to tag accounts with. Some default properties are defined, but
    270   the exchange does not do anything with these and AML SPAs are free to
    271   use any properties they like.  Account properties are only exposed
    272   to AML staff and never to the customer.
    273 * A set of *events* that are to be added to the timeline of the
    274   operator for statistical purposes.
    275 
    276 For the user-interactive *checks* we need a KYC SPA that is given:
    277 
    278 * instructions to render (with either a form to fill or links to external checks);
    279   here the context could provide an array of choices!
    280 * possibly an external check that was set up (if any); for cost-reasons, we
    281   should only do one at a time, and probably should then always redirect the
    282   browser to that check.
    283 
    284 For the staff-interactive *checks* we need an AML SPA:
    285 
    286 * to file forms and upload documentation (without state transition)
    287 * to decide on next measure (providing context); here, the exchange needs
    288   to expose the list of available *measures* and required *context* for each
    289 
    290 We need some customer-driven interactivity in KYB/KYC process, for example the
    291 user may need to be given choices (address vs. phone, individual vs. business,
    292 order in which to provide KYC data of beneficiaries). As a result, the
    293 exchange needs to serve some SPA for *measures* where the user is shown the
    294 next step(s) or choices (which person to collect KYC data on, whether to run
    295 challenger on phone number of physical address, etc.).  The SPA should also
    296 potentially contain a form to allow the customer to directly upload documents
    297 to us (like business registration) instead of to some KYC provider. This is
    298 because KYC providers may not be flexible enough.  The SPA should also allow
    299 the customer to perform KYC checks voluntarily.
    300 
    301 Similarly, the AML staff will need to be able to trigger rather complex
    302 KYB/KYC processes, like "need KYC on X and Y and Z" or "phone number or
    303 mailing address" or "please upload form A/T/S".  Here in particular it
    304 should be possible to request not only filled forms, but arbitrary
    305 documents.
    306 
    307 
    308 Terminology
    309 ^^^^^^^^^^^
    310 
    311 * **Attributes**: Attributes are used to represent KYC data obtained about
    312   an account holder. Attributes include passport images, address data,
    313   business registration documents, and indeed arbitrary forms filed by
    314   AML staff or the customer themselves.  Attribute data is considered
    315   sensitive private information and is thus stored encrypted within the
    316   exchange database.
    317 
    318 * **Check**: A check establishes a particular attribute of a user, such as
    319   their name based on an ID document and lifeness, mailing address, phone
    320   number, taxpayer identity, etc.  Checks may be given *context* (such as
    321   whether a customer is an individual or a business) to run correctly. Checks
    322   can also be AML staff inserting information for plausibilization.  Checks
    323   result in *attributes* about the account's owner which are given to an
    324   external AML *program* together with the *context* to determine an *outcome*.
    325   KYC checks are always specified with a fallback *measure* to be taken if
    326   the check fails.
    327 
    328 * **Condition**: A condition specifies when KYC is required. Conditions
    329   include the *type of operation*, a threshold amount (e.g. above EUR:1000)
    330   and possibly a time period (e.g. over the last month).
    331 
    332 * **Configuration**: The configuration determines the *legitimization rules*,
    333   and specifies which providers offer which *checks*.
    334 
    335 * **Context**: Context is information provided as input into a *check* and
    336   *program* to customize their execution. The context is initially set by the
    337   *measure* (possibly including data from the *trigger*).  Naturally, the
    338   *program* may use its `AmlProgramInput` which includes *context* and
    339   *attribute* data to compute an update *context* for the next set of
    340   *measures* that it specifies in the `LegitimizationRuleSet` as part
    341   of the `AmlOutcome`.  Thus, *context* is something that typically
    342   evolves as the *account* undergoes *measures*.  Context is lost if
    343   an account transitions to default *legitimization rules* due to
    344   *expiration*.
    345 
    346 * **Display priority**: Every rule has a *display priority*. If a second
    347   *rule* is *triggered* before the *outcome* of a *rule* could be determined,
    348   the *rule* with the larger *display priority* becomes the requirement that
    349   the account owner has to satisfy (and that thus will be displayed by the
    350   KYC SPA).
    351 
    352 * **Expiration**: Except for the default rules, any set of KYC rules is
    353   subject to *expiration*. This can be because *attributes* become outdated or
    354   because sanctions have a time limit. The expiration time thus determines
    355   when a new *measure* is triggered in the absence of a transaction crossing
    356   thresholds in the current set of *legtimization rules*.
    357 
    358 * **Legitimization rules**: The *legitimization rules* determine under which
    359   *conditions* which *measures* will be taken. A `LegitimizationRuleSet`
    360   always also includes an *expiration* time period for (custom, non-default)
    361   *legitimization rules* after which a fallback measure* will automatically
    362   apply.  Legitimization rules may be *exposed* to the client (for example,
    363   to allow a wallet to stay below hard withdraw thresholds) or could be secret.
    364 
    365 * **Logic**: Logic refers to a specific bit of code (realized as an exchange
    366   plugin) that enables the interaction with a specific *provider*.  Logic
    367   typically requires *configuration* for access control (such as an
    368   authorization token) and possibly the endpoint of the specific *provider*
    369   implementing the respective API.
    370 
    371 * **Measure**: Describes the possible outgoing edges from one state in the
    372   state machine (including how to show the current state). Each edge is given
    373   some *context* and a *check* to be performed as well as an AML *program*
    374   which determines the *outcome*.  We generally distinguish between
    375   "original" measures (defined globally in the exchange configuration) and
    376   "custom" measures (defined specifically for an account by AML staff).
    377 
    378 * **Outcome**: An `AmlOutcome` describes the account state that an account
    379   ends up in due to either an AML staff action or an AML *program* doing some
    380   computation over the attributes resulting from a *check*.  Outcomes can be
    381   that certain types of transactions are "verboten", that the account is (or
    382   remains) under investigation by AML staff, that the account is given certain
    383   properties, and/or that certain events are to be logged. Outcomes also
    384   include a new set of *legitimization rules* to apply (and an *expiration*
    385   time at which point a successor *measure* will be automatically taken).
    386 
    387 * **Provider**: A provider performs a specific set of *checks* at a certain
    388   *cost*. Interaction with a provider is performed by provider-specific
    389   *logic*.
    390 
    391 * **Program**: An AML helper *program* is given *context* about the current
    392   state of an account and the attribute data from a *check* to compute the
    393   *outcome*.  For example, a *program* may look at the "PEP" field of a KYC
    394   check and decide if the outcome is to put the account into ``normal`` or
    395   ``held-for-manual-review`` state.  AML programs are always specified
    396   with a fallback *measure* to be taken if the program fails.
    397 
    398 * **Trigger**: A specific transaction that satisfies a **Condition**.
    399 
    400 * **Type of operation**: The operation type determines which Taler-specific
    401   operation has triggered the KYC requirement. We support four types of
    402   operation: withdraw (by customer), deposit (by merchant), P2P receive (by
    403   wallet) and (high) wallet balance.
    404 
    405 
    406 Account owner authentication
    407 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
    408 
    409 Access to the KYC SPA (or rather, its account-specific state) is controlled by
    410 a *target token* (which is effectively like a bearer token, except passed
    411 inside the URL).  The *target token* ensures that only the account owner has
    412 access to the KYC processes.  It can be obtained by authenticating using
    413 either the merchant private key or reserve private key, depending on the type
    414 of the account (IBAN or wallet-reserve respectively).
    415 
    416 When we need to authenticate a bank account owner, we will simply require them
    417 to make an outgoing wire transfer into the exchange bank account with a public
    418 key in the wire transfer subject (just like when withdrawing), but augmented
    419 with the string "KYC" so we can distinguish the wire transfer from a regular
    420 withdrawal. Typically, we would put the merchant public key into the wire
    421 transfer subject; wallets MAY put their long-term reserve public key instead.
    422 The amount to be transferred is the *KYC fee*.
    423 
    424 This has several advantages:
    425 
    426 * Only the account owner can provide us with the public key, so we already
    427   have also one super-hard piece of KYC evidence.
    428 * If the account owner looses their public key, it's not a problem: they
    429   would just have to do the transfer again with a new key. No need for
    430   us to do any kind of intervention for key management.
    431 * We could theoretically get paid to do the KYC process, or just "charge" a
    432   nominal amount.
    433 * This also somewhat addresses the payment for voluntary KYC processes where
    434   a merchant wants to do KYC to get us to attest their identity for their
    435   customers even if we do not yet have a legal need.  The only issue here
    436   is that this does not work if voluntary KYC is invoiced while mandatory
    437   KYC is gratis. But, that kind of configuration is a business decision
    438   and there is no hard need to support it immediately.
    439 * This definitively addresses the need for authentication to access the
    440   attestation API, which so far was only available for P2P payments as
    441   we could not authenticate merchants.
    442 * The "KYC" string allows us to distinguish the authentication transfers from
    443   withdrawal transfers; by keeping the KYC fee at or below the closing fee,
    444   we can even deploy this without fully updating the logic everywhere to
    445   distinguish KYC transfers
    446 
    447 
    448 451 Response
    449 ^^^^^^^^^^^^
    450 
    451 When KYC operations are required, various endpoints may respond with a
    452 ``451 Unavailable for Legal Reasons`` status code and a `LegitimizationNeededResponse`
    453 body.
    454 
    455 New endpoints
    456 ^^^^^^^^^^^^^
    457 
    458 .. http:get:: /kyc-check/$H_PAYTO
    459 
    460   Checks the KYC status of a particular payment target and possibly begins a
    461   KYC process by allowing the customer to choose the next KYC measure to
    462   satisfy. This endpoint is typically used by wallets or merchants that
    463   have been told that a transaction is not happening because it triggered
    464   some KYC/AML measure and now want to check how the KYC/AML
    465   requirement could be fulfilled (or whether it already has been
    466   satisfied and the operation can now proceed).  Long-polling may be used
    467   to instantly observe a change in the KYC requirement status.
    468 
    469   The payto hash of the ``/kyc-check/`` endpoint encodes the
    470   account (or wallet) for which legitimization measures are determined.
    471   It is returned in `LegitimizationNeededResponse` responses as in
    472   the case of withdraw, the wallet may not know the debited bank account.
    473 
    474   Given a valid pair of payto hash and account owner signature, the
    475   ``/kyc-check/`` endpoint returns either just the KYC status or redirects the
    476   client (202) to the next required stage of the KYC process.  The redirection
    477   must be for an HTTP(S) endpoint to be triggered via a simple HTTP GET.  It
    478   must always be the same endpoint for the same client, as the wallet/merchant
    479   backend are not required to check for changes to this endpoint.  Clients
    480   that received a 202 status code may repeat the request and use long-polling
    481   to detect a change of the HTTP status.
    482 
    483   **Request:**
    484 
    485   *Account-Owner-Signature*:
    486     The client must provide Base-32 encoded EdDSA signature with
    487     ``$ACCOUNT_PRIV``, affirming the desire to obtain KYC data.  Note that
    488     this is merely a simple authentication mechanism, the details of the
    489     request are not protected by the signature.  The ``$ACCOUNT_PRIV`` is
    490     either the (wallet long-term) reserve private key or the merchant instance
    491     private key.
    492 
    493   :query timeout_ms=NUMBER: *Optional.*  If specified, the exchange will
    494     wait up to ``timeout_ms`` milliseconds if the requirement continues
    495     to be mandatory provisioning of KYC data by the client.
    496     Ignored if the HTTP status code is already ``200 Ok``.  Note that
    497     clients cannot long-poll for AML staff actions, so status information
    498     about an account being under AML review needs to be requested
    499     periodically.
    500 
    501   **Response:**
    502 
    503   :http:statuscode:`200 Ok`:
    504     No mandatory KYC actions are required by the client at this time.
    505     The client *may* still visit the KYC URL to initiate voluntary checks.
    506     The response will be an `AccountKycStatus` object which specifies
    507     restrictions that currently apply to the account. If the
    508     client attempts to exceed *soft* limits, the status may change
    509     to a ``202 Accepted``.  Hard limits cannot be lifted by passing KYC checks.
    510   :http:statuscode:`202 Accepted`:
    511     The account holder performed an operation that would have crossed
    512     *soft* limits and must be redirected to the provided location to perform
    513     the required KYC checks to satisfy the legal requirements. Afterwards, the
    514     ``/kyc-check/`` request should be repeated to check whether the
    515     user has completed the process.
    516     The response will be an `AccountKycStatus` object.
    517   :http:statuscode:`204 No content`:
    518     The exchange is not configured to perform KYC and thus
    519     the legal requirements are already satisfied.
    520   :http:statuscode:`403 Forbidden`:
    521     The provided signature is not acceptable for the payto hash.
    522   :http:statuscode:`404 Not found`:
    523     The requirement row is unknown.
    524 
    525 .. http:get:: /aml-spa/$FILENAME
    526 
    527   Serves the resources of the AML SPA.
    528 
    529 .. http:get:: /kyc-spa/$FILENAME
    530 
    531   Serves the resources of the KYC SPA. Note that
    532   ``$FILENAME`` must be syntactically distinct from
    533   the access token.  Any ``$ACCESS_TOKEN`` will be
    534   mapped internally to "index.html".
    535 
    536 .. http:get:: /kyc-spa/$ACCESS_TOKEN
    537 
    538   A set of ``/kyc-spa/$ACCESS_TOKEN`` GET endpoints is created per account
    539   hash that serves the KYC SPA.  This is where the ``/kyc-check/`` endpoint
    540   will in principle redirect clients.  The KYC SPA will use the
    541   ``$ACCESS_TOKEN`` of its URL to initialize itself via the
    542   ``/kyc-info/$ACCESS_TOKEN`` endpoint family.  The KYC SPA may download
    543   additional resources via ``/kyc-spa/$FILENAME``. The filenames must not
    544   match base32-encoded 256-bit values.
    545 
    546 .. http:get:: /kyc-info/$ACCESS_TOKEN
    547 
    548   The ``/kyc-info/$ACCESS_TOKEN`` endpoints are created per client
    549   account hash (but access controlled via a unique target token)
    550   to return information about the state of the KYC or AML process
    551   to the KYC SPA.  The SPA uses this information to show the user an
    552   appropriate dialog. The SPA should also long-poll this endpoint for changes
    553   to the AML/KYC state. Note that this is a client-facing endpoint, so it will
    554   only provide a restricted amount of information to the customer (as some
    555   laws may forbid us to inform particular customers about their true status).
    556   The endpoint will typically inform the SPA about possible choices to
    557   proceed, such as directly uploading files, contacting AML staff, or
    558   proceeding with a particular KYC process at an external provider (such as
    559   Challenger).  If the user chooses to initate a KYC process at an external
    560   provider, the SPA must request the respective process to be set-up by the
    561   exchange via the ``/kyc-start/`` endpoint.
    562 
    563   **Request:**
    564 
    565   *If-None-Match*:
    566     The client MAY provide an ``If-None-Match`` header with an ETag.
    567 
    568   :query timeout_ms=MILLISECONDS:
    569     *Optional.* If specified, the exchange will wait up to MILLISECONDS for
    570     a change to a more recent legitimization measure before returning a 304
    571     Not Modified status.
    572 
    573   **Response:**
    574 
    575   *Etag*: Will be set to the serial ID of the measure. Used for long-polling (only for 200 OK responses).
    576 
    577   :http:statuscode:`200 OK`:
    578     The body is a `KycProcessClientInformation`.
    579   :http:statuscode:`204 No Content`:
    580     There are no open KYC requirements or possible voluntary checks
    581     the client might perform.
    582   :http:statuscode:`304 Not Modified`:
    583     The KYC requirements did not change.
    584 
    585 
    586 .. http:post:: /kyc-upload/$ID
    587 
    588   The ``/kyc-upload/$ID`` POST endpoint allows the SPA to upload
    589   client-provided evidence.  The ``$ID`` will be provided as part of the
    590   ``/kyc-info`` body.  This is for checks of type ``FORM``.  In practice,
    591   ``$ID`` will encode both the ``$ACCESS_TOKEN`` and the index of the selected
    592   measure (but this should be irrelevant for the client).
    593 
    594   **Request:**
    595 
    596   Basically oriented along the possible formats of a HTTP form being
    597   POSTed. Details will depend on the form. The server will try to decode the
    598   uploaded body from whatever format it is provided in.
    599 
    600   **Response:**
    601 
    602   :http:statuscode:`204 No Content`:
    603     The information was successfully uploaded. The SPA should fetch
    604     an updated ``/kyc-info/``.
    605   :http:statuscode:`404 Not Found`:
    606     The ``$ID`` is unknown to the exchange.
    607   :http:statuscode:`409 Conflict`:
    608     The upload conflicts with a previous upload.
    609   :http:statuscode:`413 Request Entity Too Large`:
    610     The body is too large.
    611 
    612 .. http:post:: /kyc-start/$ID
    613 
    614   The ``/kyc-start/$ID`` POST endpoint allows the SPA to set up a new external
    615   KYC process. It will return the URL that the client must GET to begin the
    616   KYC process. The SPA should probably open this URL in a new window or tab.
    617   The ``$ID`` will be provided as part of the ``/kyc-info`` body.  In
    618   practice, ``$ID`` will encode both the ``$ACCESS_TOKEN`` and the index of
    619   the selected measure (but this should be irrelevant for the client).
    620 
    621   **Request:**
    622 
    623   Use empty JSON body for now.
    624 
    625   **Response:**
    626 
    627   :http:statuscode:`200 Ok`:
    628     The KYC process was successfully initiated. The URL is in a
    629     `KycProcessStartInformation` object.
    630 
    631   :http:statuscode:`404 Not Found`:
    632     The ``$ID`` is unknown to the exchange.
    633 
    634   .. note::
    635 
    636     As this endpoint is involved in every KYC check at the beginning, this
    637     is also the place where we could integrate the payment process for the KYC fee
    638     in the future (since **vATTEST**).
    639 
    640 
    641 .. http:get:: /kyc-proof/$PROVIDER_SECTION?state=$H_PAYTO
    642 
    643   Upon completion of the process at the external KYC provider, the provider
    644   must redirect the client (browser) to trigger a GET request to a new
    645   ``/kyc-proof/$H_PAYTO/$PROVIDER_SECTION`` endpoint.  Once this endpoint is
    646   triggered, the exchange will pass the received arguments to the respective
    647   logic plugin.  The logic plugin will then (asynchronously) update the KYC
    648   status of the user.  The logic plugin should redirect the user to the KYC
    649   SPA. This endpoint deliberately does not use the ``$ACCESS_TOKEN`` as the
    650   external KYC provider should not learn that token.
    651 
    652   This endpoint is thus accessed from the user's browser at the *end* of a KYC
    653   process, possibly providing the exchange with additional credentials to
    654   obtain the results of the KYC process.  Specifically, the URL arguments
    655   should provide information to the exchange that allows it to verify that the
    656   user has completed the KYC process. The details depend on the logic, which
    657   is selected by the "$PROVIDER_SECTION".
    658 
    659   While this is a GET (and thus safe, and idempotent), the operation may
    660   actually trigger significant changes in the exchange's state.  In
    661   particular, it may update the KYC status of a particular payment target.
    662 
    663   **Request:**
    664 
    665   Details on the request depend on the specific KYC logic that was used.
    666 
    667   If the KYC plugin logic is OAuth 2.0, the query parameters are:
    668 
    669   :query code=CODE:
    670      OAuth 2.0 code argument.
    671   :query state=STATE:
    672      OAuth 2.0 state argument with the H_PAYTO.
    673 
    674   .. note::
    675 
    676     Depending on the OAuth variant used, additional
    677     query parameters may need to be passed here.
    678 
    679   **Response:**
    680 
    681   Given that the response is returned to a user using a browser and **not** to
    682   a Taler wallet, the response format is in human-readable HTML and not in
    683   machine-readable JSON.
    684 
    685   :http:statuscode:`302 Found`:
    686     The KYC operation succeeded and the
    687     payment target is now authorized to transact.
    688     The browser is redirected to a human-readable
    689     page configured by the exchange operator.
    690   :http:statuscode:`401 Unauthorized`:
    691     The provided authorization token is invalid.
    692   :http:statuscode:`404 Not found`:
    693     The payment target is unknown.
    694   :http:statuscode:`502 Bad Gateway`:
    695     The exchange received an invalid reply from the
    696     legitimization service.
    697   :http:statuscode:`504 Gateway Timeout`:
    698     The exchange did not receive a reply from the legitimization
    699     service within a reasonable time period.
    700 
    701 
    702 .. http:get:: /kyc-webhook/$PROVIDER_SECTION/*
    703 .. http:post:: /kyc-webhook/$PROVIDER_SECTION/*
    704 .. http:get:: /kyc-webhook/$LOGIC/*
    705 .. http:post:: /kyc-webhook/$LOGIC/*
    706 
    707   Alternatively, the KYC confirmation may be triggered by a ``/kyc-webhook``
    708   request. As KYC **providers** do not necessarily support passing detailed
    709   information in the URL arguments, the ``/kyc-webhook`` only needs to specify
    710   either the ``PROVIDER_SECTION`` *or* the ``LOGIC`` (the name of the plugin
    711   implementing the KYC API).  The API-specific webhook logic must then figure
    712   out what exactly the webhook is about on its own.  The ``/kyc-webhook/``
    713   endpoint works for GET or POST, again as details depend on the KYC provider.
    714   In contrast to ``kyc-proof``, the response does NOT go to the end-users'
    715   browser and should thus only indicate success or failure.
    716 
    717   **Request:**
    718 
    719   Details on the request depend on the specific KYC logic that was used.
    720 
    721   **Response:**
    722 
    723   :http:statuscode:`204 No content`:
    724     The operation succeeded.
    725   :http:statuscode:`404 Not found`:
    726     The specified logic is unknown.
    727 
    728 
    729 .. http:post:: /kyc-wallet
    730 
    731   The ``/kyc-wallet`` POST endpoint allows a wallet to notify an exchange if
    732   it will cross a balance threshold.  Here, the ``balance`` specified should be
    733   the threshold (from the ``wallet_balance_limit_without_kyc`` array) that the
    734   wallet would cross, and *not* the *exact* balance of the wallet.  The exchange
    735   will respond with a wire target UUID. The wallet can then use this UUID to
    736   begin the KYC process at ``/kyc-check/``. The wallet must only proceed to
    737   obtain funds exceeding the threshold after the KYC process has concluded.
    738   While wallets could be "hacked" to bypass this measure (we cannot
    739   cryptographically enforce this), such modifications are a terms of service
    740   violation which may have legal consequences for the user.
    741 
    742   Setup KYC identification for a wallet.  Returns the KYC UUID.  This endpoint
    743   is used by compliant Taler wallets when they are about to hit the balance
    744   threshold and thus need to have the customer provide their personal details
    745   to the exchange.  The wallet is identified by its long-lived reserve public
    746   key (which is used for P2P payments, not for withdrawals).
    747 
    748   **Request:**
    749 
    750   The request body must be a `WalletKycRequest` object.
    751 
    752   **Response:**
    753 
    754   :http:statuscode:`204 No Content`:
    755     KYC is disabled at this exchange, or the balance is below the
    756     threshold that requires KYC, or this wallet already satisfied
    757     the KYC check for the given balance.
    758   :http:statuscode:`403 Forbidden`:
    759     The provided signature is invalid.
    760     This response comes with a standard `ErrorDetail` response.
    761   :http:statuscode:`451 Unavailable for Legal Reasons`:
    762     The wallet must undergo a KYC check. A KYC ID was created.
    763     The response will be a `LegitimizationNeededResponse` object.
    764 
    765 .. http:get:: /aml/$OFFICER_PUB/measures
    766 
    767   To enable the AML staff SPA to give AML staff a choice of possible measures, a
    768   new endpoint ``/aml/$OFFICER_PUB/measures`` is added that allows the AML SPA
    769   to dynamically GET the list of available measures.  It returns a list of known
    770   KYC checks (by name) with their descriptions and a list of AML programs with
    771   information about the required context.
    772 
    773   **Request:**
    774 
    775   *Taler-AML-Officer-Signature*:
    776     The client must provide Base-32 encoded EdDSA signature with
    777     ``$OFFICER_PRIV``, affirming the desire to obtain AML data.  Note that
    778     this is merely a simple authentication mechanism, the details of the
    779     request are not protected by the signature.
    780 
    781   **Response:**
    782 
    783   :http:statuscode:`200 Ok`:
    784     Information about possible measures is returned in a
    785     `AvailableMeasureSummary` object.
    786 
    787 .. http:get:: /aml/$OFFICER_PUB/kyc-statistics/$NAME
    788 
    789   Returns the number of KYC events matching the given event type ``$NAME`` in
    790   the specified time range.  Note that this query can be slow as the
    791   statistics are computed on-demand. (This is OK as such requests should be
    792   rare.)
    793 
    794   **Request:**
    795 
    796   *Taler-AML-Officer-Signature*:
    797     The client must provide Base-32 encoded EdDSA signature with
    798     ``$OFFICER_PRIV``, affirming the desire to obtain AML data.  Note that this
    799     is merely a simple authentication mechanism, the details of the request are
    800     not protected by the signature.
    801 
    802   :query start_date=TIMESTAMP:
    803     *Optional*. Specifies the date when to
    804     start looking (inclusive). If not given, the start time of the
    805     exchange operation is used.
    806   :query end_date=TIMESTAMP:
    807     *Optional*. Specifies the date when to
    808     stop looking (exclusive). If not given, the current date is used.
    809 
    810   **Response:**
    811 
    812   :http:statuscode:`200 OK`:
    813     The response will be an `EventCounter` message.
    814 
    815 .. http:get:: /aml/$OFFICER_PUB/decisions
    816 
    817   **Request:**
    818 
    819   *Taler-AML-Officer-Signature*:
    820     The client must provide Base-32 encoded EdDSA signature with
    821     ``$OFFICER_PRIV``, affirming the desire to obtain AML data.  Note that
    822     this is merely a simple authentication mechanism, the details of the
    823     request are not protected by the signature.
    824 
    825   :query limit:
    826     *Optional*. takes value of the form ``N (-N)``, so that at
    827     most ``N`` values strictly older (younger) than ``start`` are returned.
    828     Defaults to ``-20`` to return the last 20 entries (before ``start``).
    829   :query offset:
    830     *Optional*. Row number threshold, see ``delta`` for its
    831     interpretation.  Defaults to ``INT64_MAX``, namely the biggest row id
    832     possible in the database.
    833   :query h_payto:
    834     *Optional*. Account selector. All matching accounts are returned if this
    835     filter is absent, otherwise only decisions for this account.
    836   :query active:
    837     *Optional*. If set to yes, only return active decisions, if no only
    838     decisions that have been superseded. Do not give (or use "all") to
    839     see all decisions regardless of activity status.
    840   :query investigation:
    841     *Optional*. If set to yes, only return accounts that are under
    842     AML investigation, if no only accounts that are not under investigation.
    843     Do not give (or use "all") to see all accounts regardless of
    844     investigation status.
    845 
    846   **Response:**
    847 
    848   :http:statuscode:`200 OK`:
    849     The response will be an `AmlDecisionsResponse` message.
    850   :http:statuscode:`204 No content`:
    851     There are no matching AML records.
    852   :http:statuscode:`403 Forbidden`:
    853     The signature is invalid.
    854   :http:statuscode:`404 Not found`:
    855     The designated AML account is not known.
    856   :http:statuscode:`409 Conflict`:
    857     The designated AML account is not enabled.
    858 
    859 .. http:get:: /aml/$OFFICER_PUB/attributes/$H_PAYTO
    860 
    861   Obtain attributes obtained as part of AML/KYC processes for a
    862   given account.
    863 
    864   **Request:**
    865 
    866   *Taler-AML-Officer-Signature*:
    867     The client must provide Base-32 encoded EdDSA signature with
    868     ``$OFFICER_PRIV``, affirming the desire to obtain AML data.  Note that
    869     this is merely a simple authentication mechanism, the details of the
    870     request are not protected by the signature.
    871 
    872   :query limit:
    873     *Optional*. takes value of the form ``N (-N)``, so that at
    874     most ``N`` values strictly older (younger) than ``start`` are returned.
    875     Defaults to ``-20`` to return the last 20 entries (before ``start``).
    876   :query offset:
    877     *Optional*. Row number threshold, see ``delta`` for its
    878     interpretation.  Defaults to ``INT64_MAX``, namely the biggest row id
    879     possible in the database.
    880 
    881   **Response:**
    882 
    883   :http:statuscode:`200 OK`:
    884     The response will be an `KycAttributesResponse` message.
    885   :http:statuscode:`204 No content`:
    886     There are no matching KYC attributes.
    887   :http:statuscode:`403 Forbidden`:
    888     The signature is invalid.
    889   :http:statuscode:`404 Not found`:
    890     The designated AML account is not known.
    891   :http:statuscode:`409 Conflict`:
    892     The designated AML account is not enabled.
    893 
    894 .. http:post:: /aml/$OFFICER_PUB/decision
    895 
    896   Make an AML decision. Triggers the respective action and
    897   records the justification.
    898 
    899   **Request:**
    900 
    901   The request body must be an `AmlDecisionRequest` message.
    902 
    903   **Response:**
    904 
    905   :http:statuscode:`204 No Content`:
    906     The AML decision has been executed and recorded successfully.
    907   :http:statuscode:`403 Forbidden`:
    908     The signature is invalid.
    909   :http:statuscode:`404 Not Found`:
    910     The address the decision was made upon is unknown to the exchange or
    911     the designated AML account is not known.
    912   :http:statuscode:`409 Conflict`:
    913     The designated AML account is not enabled or a more recent
    914     decision was already submitted.
    915 
    916 Modifications to existing endpoints
    917 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
    918 
    919 .. note::
    920 
    921    This subsection describes an earlier KYC API design.  The core exchange API
    922    and KYC manual supersede its endpoint names and processing model.
    923 
    924 When withdrawing, the exchange checks if the KYC status is acceptable.  If no
    925 KYC was done and if either the amount withdrawn over a particular timeframe
    926 exceeds the threshold or the reserve received a P2P transfer, then a
    927 ``451 Unavailable for Legal Reasons`` is returned which redirects the consumer
    928 to the new ``/kyc-check/`` handler.
    929 
    930 When depositing, the exchange aggregator (!) checks the KYC status and if
    931 negative, returns an additional information field via the
    932 ``aggregation_transient`` table which is returned via GET ``/deposits/`` to the
    933 merchant.
    934 
    935 When merging into a reserve, the KYC status is checked and again the
    936 merge fails with ``451 Unavailable for Legal Reasons`` to trigger the
    937 KYC process.
    938 
    939 To allow the wallet to do the KYC check if it is about to exceed a set balance
    940 threshold, we modify the ``/keys`` response to add an optional array
    941 ``wallet_balance_limit_without_kyc`` of threshold amounts is returned.
    942 Whenever the wallet crosses one of these thresholds for the first time, it
    943 should trigger the KYC process.  If this field is absent, there is no limit.
    944 If the field is provided, a correct wallet must create a long-term
    945 account-reserve key pair. This should be the same key that is also used to
    946 receive wallet-to-wallet payments. Then, *before* a wallet performs an
    947 operation that would cause it to exceed the balance threshold in terms of
    948 funds held from a particular exchange, it *should* first request the user to
    949 complete the KYC process.  For that, the wallet should POST to the new
    950 ``/kyc-wallet`` endpoint, providing its long-term reserve-account public key
    951 and a signature requesting permission to exceed the account limit.
    952 
    953 
    954 Configuration of external KYC providers
    955 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
    956 
    957 For each KYC provider that could contribute to checks the configuration
    958 specifies a ``$PROVIDER_SECTION`` for each authentication procedure.  For each
    959 (enabled) provider, the exchange has a logic plugin which (asynchronously)
    960 determines the redirect URL for a given wire target. See below for a
    961 description of the high-level process for different providers.
    962 
    963 .. code-block:: ini
    964 
    965   [kyc-provider-$PROVIDER_ID]
    966 
    967   # Which plugin is responsible for this provider?
    968   LOGIC = PLUGIN_NAME
    969 
    970   # Plus additional logic-specific options, e.g.:
    971   AUTHORIZATION_TOKEN = superdupersecret
    972 
    973   # Other logic-specific internal options (example):
    974   FORM_ID = business_legi_form
    975 
    976 
    977 Configuration of possible KYC/AML checks
    978 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
    979 
    980 The configuration specifies a set of possible KYC checks offered by external
    981 providers, one per configuration section:
    982 
    983 .. code-block:: ini
    984 
    985   [kyc-check-$CHECK_NAME]
    986 
    987   # Which type of check is this? Also determines
    988   # the SPA form to show to the user for this check.
    989   #
    990   # INFO: wait for staff or contact staff out-of band
    991   #          (only information shown, no SPA action)
    992   # FORM: SPA should show an inline (HTML) form
    993   # LINK: SPA may start external KYC process or upload
    994   #
    995   TYPE = INFO|LINK|FORM
    996 
    997   # Provider id, present only if type is LINK.
    998   # Refers to a ``kyc-provider-$PROVIDER_ID`` section.
    999   PROVIDER_ID = id
   1000 
   1001   # Name of the SPA form, if type is FORM
   1002   # "INFO" and "LINK" are reserved and must not be used.
   1003   # The exchange server and the SPA must agree on a list
   1004   # of supported forms and the resulting attributes.
   1005   #
   1006   # The SPA should include a JSON resource file
   1007   # "forms.json" mapping form names to arrays of
   1008   # attribute names each form provides.
   1009   FORM_NAME = name
   1010 
   1011   # Descriptions to use in the SPA to display the check.
   1012   DESCRIPTION = "Upload your passport picture"
   1013   DESCRIPTION_I18N = "{"en":"Upload scan of your passport"}"
   1014 
   1015   # ';'-separated list of fields that the CONTEXT must
   1016   # provide as inputs to this check. For example,
   1017   # for a FORM of type CHOICE, this might state
   1018   # ``choices: string[];``. The type after the ":"
   1019   # is for now purely for documentation and is
   1020   # not checked. However, it may be shown to AML staff
   1021   # when they configure measures.
   1022   REQUIRES = requirement;
   1023 
   1024   # Description of the outputs provided by the check.
   1025   # Basically, the check's output is expected to
   1026   # provide the following fields as attribute inputs into
   1027   # a subsequent AML program.
   1028   # Only given for type FORM; INFO never has any outputs,
   1029   # and for type LINK we can obtain the same information
   1030   # from the CONVERTER via ``--list-outputs``.
   1031   OUTPUTS = business_name street city country registration
   1032 
   1033   # **original** measure to take if the check fails
   1034   # (for any reason, e.g. provider or form fail to
   1035   # satisfy constraints or provider signals user error)
   1036   # Usually should point to a measure that requests
   1037   # AML staff to investigate.  The fallback measure
   1038   # context always includes the reasons for the
   1039   # failure.
   1040   FALLBACK = MEASURE_NAME
   1041 
   1042 The list of possible FORM names is fixed in the SPA
   1043 for a particular exchange release.
   1044 
   1045 The outcome of *any* check should always be uploaded encrypted into the
   1046 ``kyc_attributes`` table.  It MUST include an ``expiration_time``.
   1047 
   1048 The "check_name" value "skip" is reserved and must not be defined. It can be
   1049 used in measures where the AML program must be run immediately without any
   1050 input.
   1051 
   1052 
   1053 Configuration of legitimization requirement triggers
   1054 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
   1055 
   1056 The configuration also specifies a set of legitimization rules including the
   1057 condition and the measure the condition triggers, one condition per
   1058 configuration section:
   1059 
   1060 .. code-block:: ini
   1061 
   1062   [kyc-rule-$RULE_NAME]
   1063 
   1064   # Operation that triggers this rule.
   1065   # Must be one of "WITHDRAW", "DEPOSIT",
   1066   # (p2p) "MERGE", (wallet) "BALANCE",
   1067   # (reserve) "CLOSE", "AGGREGATE",
   1068   # "TRANSACTION" or "REFUND".
   1069   OPERATION_TYPE = WITHDRAW
   1070 
   1071   # Space-separated list of next measures to be performed.
   1072   # The SPA should display *all* of these measures to the user.
   1073   # (They have a choice of either which ones, or in
   1074   # which order they are to be performed.)
   1075   # A special measure name "verboten" is used if the
   1076   # specified threshold may never be crossed
   1077   # (under this set of rules).
   1078   NEXT_MEASURES = SWISSNESS KYB
   1079 
   1080   # "YES" if all NEXT_MEASURES will eventually need
   1081   # to be satisfied, "NO" if the user has a choice between
   1082   # them. Not actually enforced by the exchange, but
   1083   # primarily used to inform the user whether this is
   1084   # an "and" or "or". YES for "and".
   1085   IS_AND_COMBINATOR = YES
   1086 
   1087   # YES if the rule (specifically, operation type,
   1088   # threshold, timeframe) and the general nature of
   1089   # the next measure (verboten or approval required)
   1090   # should be exposed to the client.
   1091   # Defaults to NO if not set.
   1092   EXPOSED = YES
   1093 
   1094   # Threshold amount above which the rule is
   1095   # triggered.  The total must be exceeded in the given
   1096   # timeframe.
   1097   THRESHOLD = KUDOS:100
   1098 
   1099   # Timeframe over which the amount to be compared to
   1100   # the THRESHOLD is calculated.
   1101   # Ignored for WALLET-BALANCE.  Can be 'forever'.
   1102   TIMEFRAME = 30 days
   1103 
   1104   # Set to YES to enable the rule (default is NO)
   1105   ENABLED = NO
   1106 
   1107 
   1108 AML programs
   1109 ^^^^^^^^^^^^
   1110 
   1111 AML programs are helper programs that can:
   1112 
   1113 * Generate a list of *required* context field names
   1114   for the helper (introspection!) using the "--required-context"
   1115   command-line switch. The output should use the same
   1116   syntax as the REQUIRES clause of ``[kyc-check-]``
   1117   configuration sections, except that new lines
   1118   MUST be used to separate fields instead of ";".
   1119 * Generate a list of *required* attribute names
   1120   for the helper (introspection!) using the "--required-attributes"
   1121   command-line switch. The output should use the same
   1122   list of names as the ATTRIBUTES in the
   1123   ``[kyc-provider-]`` configuration section
   1124   (but may also include FORM field names).
   1125 * Process an input JSON object of type
   1126   `AmlProgramInput` into a JSON object of
   1127   type `AmlOutcome`.
   1128   This is the default behavior if no command-line switches
   1129   are provided.
   1130 
   1131 If the AML program fails (exits with a failure code or
   1132 does not provide well-formed JSON output) the AML/KYC
   1133 process continues with the FALLBACK measure. This should
   1134 usually be one that asks AML staff to contact the
   1135 systems administrator.
   1136 
   1137 AML programs are listed in the configuration file, one program per section:
   1138 
   1139 .. code-block:: ini
   1140 
   1141   [aml-program-$PROG_NAME]
   1142 
   1143   # Program to run.
   1144   COMMAND = taler-helper-aml-pep
   1145 
   1146   # Human-readable description of what this
   1147   # AML helper program will do. Used to show
   1148   # to the AML staff.
   1149   DESCRIPTION = "check if the customer is a PEP"
   1150 
   1151   # True if this AML program is enabled (and thus can be
   1152   # used in measures and exposed to AML staff).
   1153   # Optional, default is NO.
   1154   ENABLED = YES
   1155 
   1156   # **original** measure to take if COMMAND fails
   1157   # Usually points to a measure that asks AML staff
   1158   # to contact the systems administrator. The fallback measure
   1159   # context always includes the reasons for the
   1160   # failure.
   1161   FALLBACK = MEASURE_NAME
   1162 
   1163 
   1164 Configuration of measures
   1165 ^^^^^^^^^^^^^^^^^^^^^^^^^
   1166 
   1167 Finally, the configuration specifies a set of
   1168 **original** *measures* one per configuration section:
   1169 
   1170 .. code-block:: ini
   1171 
   1172   [kyc-measure-$MEASURE_NAME]
   1173 
   1174   # Possible check for this measure.  Optional.
   1175   # If not given, PROGRAM should be run immediately
   1176   # (on an empty set of attributes).
   1177   CHECK_NAME = IB_FORM
   1178 
   1179   # Context for the check. The context can be
   1180   # just an empty JSON object if there is none.
   1181   CONTEXT = {"choices":["individual","business"]}
   1182 
   1183   # Program name to run on the context and check data to
   1184   # determine the outcome and next measure.
   1185   # Refers to a ``[aml-program-$PROG_NAME]`` section name.
   1186   PROGRAM = taler-aml-program
   1187 
   1188   # Optional. Set to YES to allow this measure to be
   1189   # done voluntarily by a client. Used to offer the
   1190   # KYC SPA to display measure even if they are
   1191   # not required. Default is NO.
   1192   VOLUNTARY = YES/NO
   1193 
   1194 
   1195 If ``CHECK_NAME`` is set to "SKIP" (or is not provided at all), the AML
   1196 ``PROGRAM`` is to be run immediately.  This is useful if no client-interaction
   1197 is required to arrive at a decision.
   1198 
   1199 .. note::
   1200 
   1201   The list of *measures* is not complete: AML staff may freely define new
   1202   measures dynamically, usually by selecting checks, an AML program, and
   1203   providing context.
   1204 
   1205 
   1206 Sanity checking
   1207 ^^^^^^^^^^^^^^^
   1208 
   1209 On start-up, ``taler-exchange-httpd`` should sanity-check its
   1210 configuration. Specifically, it should validate that for all AML programs the
   1211 input requirements (attributes and context) are claimed to be satisfied by the
   1212 respective checks that may trigger those programs, and similarly that for all
   1213 checks the original measures satisfy the context requirements for their KYC
   1214 checks.
   1215 
   1216 As a result, any component (AML program, form or external check) is warranted
   1217 to be always called with the declared required inputs. Furthermore, we can
   1218 detect if a component fails to produce the required output and the
   1219 configuration contains (presumably safe) FALLBACKs to address this case.  The
   1220 exchange *MUST* detect circular failures, like when a FALLBACK triggers a
   1221 measure that itself immediately triggers again the same FALLBACK.
   1222 
   1223 
   1224 Exchange database schema
   1225 ^^^^^^^^^^^^^^^^^^^^^^^^
   1226 
   1227 We introduce a new ``wire_targets`` table into the exchange database. This
   1228 table is referenced as the source or destination of payments (regular deposits
   1229 and also P2P payments).  A positive side-effect is that we reduce duplication
   1230 in the ``reserves_in``, ``wire_out`` and ``deposits`` tables as they can
   1231 reference this table.
   1232 
   1233 We introduce a new ``legitimization_processes`` table that tracks the status
   1234 of a legitimization process at a provider, including the configuration section
   1235 name, the user/account name at the provider, and some legitimization
   1236 identifier for the process at the provider.  In this table, we additionally
   1237 store information related to the KYC status of the underlying payto://-URI, in
   1238 particular when the KYC expires (0 if it was never done).
   1239 
   1240 Finally, we introduce a new ``legitimization_requirements`` table that
   1241 contains a list of checks required for a particular wire target.  When KYC is
   1242 triggered (say when some endpoint returns an HTTP status code of 451) a
   1243 new requirement is first put into the requirements table. Then, when the
   1244 client identifies as business or individual the specific legitimization
   1245 process is started.  When the taler-exchange-aggregator triggers a KYC check
   1246 the merchant can observe this when a 202 (Accepted) status code is returned
   1247 on GET ``/deposits/`` with the respective legitimization requirement row.
   1248 
   1249 
   1250 .. sourcecode:: sql
   1251 
   1252   CREATE TABLE wire_targets
   1253     (wire_target_serial_id BIGSERIAL UNIQUE
   1254     ,wire_target_h_payto BYTEA PRIMARY KEY CHECK (LENGTH(wire_target_h_payto)=32),
   1255     ,access_token BYTEA UNIQUE CHECK (LENGTH(access_token)=32) DEFAULT gen_random_bytes(32)
   1256     ,target_pub BYTEA CHECK (LENGTH(target_pub)=32) DEFAULT NULL
   1257     ,payto_uri STRING NOT NULL
   1258     )
   1259     PARTITION BY HASH (wire_target_h_payto);
   1260 
   1261   COMMENT ON TABLE wire_targets
   1262     IS 'All recipients of money via the exchange';
   1263   COMMENT ON COLUMN wire_targets.h_payto
   1264     IS 'Unsalted hash of payto_uri';
   1265   COMMENT ON COLUMN wire_targets.access_token
   1266     IS 'high-entropy random value that is used as a token to authorize access to the KYC process (without requiring a signature by target_priv)';
   1267   COMMENT ON COLUMN wire_targets.target_pub
   1268     IS 'Public key (reserve_pub or merchant_pub) associated with the account; NULL if KYC is not allowed for the account (if there was no incoming KYC wire transfer yet); updated, thus NOT available to the auditor';
   1269   COMMENT ON COLUMN wire_targets.payto_uri
   1270     IS 'Can be a regular bank account, or also be a URI identifying a reserve-account (for P2P payments)';
   1271 
   1272   CREATE TABLE IF NOT EXISTS legitimization_measures
   1273     (legitimization_measure_serial_id INT8 GENERATED BY DEFAULT AS IDENTITY
   1274     ,access_token BYTEA NOT NULL UNIQUE CHECK (LENGTH(access_token)=32)
   1275      REFERENCES wire_targets (access_token)
   1276     ,start_time INT8 NOT NULL
   1277     ,jmeasures TEXT NOT NULL
   1278     ,display_priority INT4 NOT NULL
   1279     ,is_finished BOOL NOT NULL DEFAULT(FALSE)
   1280     )
   1281     PARTITION BY HASH (access_token);
   1282 
   1283   COMMENT ON TABLE legitimization_measures
   1284     IS 'Rules that have been triggered for the account (FIXME: check this is consistent with usage)';
   1285   COMMENT ON COLUMN legitimization_measures.access_token
   1286     IS 'Used to uniquely identify the account and as a symmetric access control mechanism for the SPA';
   1287   COMMENT ON COLUMN legitimization_measures.start_time
   1288     IS 'Time when the measure was triggered (by decision or rule)';
   1289   COMMENT ON COLUMN legitimization_measures.jmeasures
   1290     IS 'JSON object of type LegitimizationMeasures with KYC/AML measures for the account encoded';
   1291   COMMENT ON COLUMN legitimization_measures.display_priority
   1292     IS 'Display priority of the rule that triggered this measure; if in the meantime another rule also triggers, the measure is only replaced if the new rule has a higher display priority';
   1293   COMMENT ON COLUMN legitimization_measures.is_finished
   1294     IS 'Set to TRUE if this set of measures was processed; used to avoid indexing measures that are done';
   1295 
   1296   CREATE INDEX ON legitimization_measures (access_token)
   1297     WHERE NOT is_finished;
   1298 
   1299   CREATE TABLE legitimization_outcomes
   1300     (outcome_serial_id INT8 GENERATED BY DEFAULT AS IDENTITY
   1301     ,h_payto BYTEA CHECK (LENGTH(h_payto)=32)
   1302      REFERENCES wire_targets (wire_target_h_payto)
   1303     ,decision_time INT8 NOT NULL DEFAULT(0)
   1304     ,expiration_time INT8 NOT NULL DEFAULT(0)
   1305     ,jproperties TEXT,
   1306     ,new_measure_name TEXT,
   1307     ,to_investigate BOOL NOT NULL
   1308     ,is_active BOOL NOT NULL DEFAULT(TRUE)
   1309     ,jnew_rules TEXT NOT NULL
   1310     )
   1311     PARTITION BY HASH (h_payto);
   1312 
   1313   COMMENT ON TABLE legitimization_outcomes
   1314     IS 'Outcomes can come from AML programs';
   1315   COMMENT ON COLUMN legitimization_outcomes.h_payto
   1316     IS 'hash of the payto://-URI this outcome is about';
   1317   COMMENT ON COLUMN legitimization_outcomes.decision_time
   1318     IS 'when was this outcome decided';
   1319   COMMENT ON COLUMN legitimization_outcomes.expiration_time
   1320     IS 'time when the decision expires and the expiration jnew_rules should be applied';
   1321   COMMENT ON COLUMN legitimization_outcomes.jproperties
   1322     IS 'JSON object of type AccountProperties, such as PEP status, business domain, risk assessment, etc.';
   1323   COMMENT ON COLUMN legitimization_outcomes.to_investigate
   1324     IS 'AML staff should investigate the activity of this account';
   1325   COMMENT ON COLUMN legitimization_outcomes.is_active
   1326     IS 'TRUE if this is the current authoritative legitimization outcome';
   1327   COMMENT ON COLUMN legitimization_outcomes.new_measure_name
   1328     IS 'space-separated list of measures to trigger immediately, NULL for none, prefixed with a "+" to indicate AND combination for the measures';
   1329   COMMENT ON COLUMN legitimization_outcomes.jnew_rules
   1330     IS 'JSON object of type LegitimizationRuleSet with rules to apply to the various operation types for this account; all KYC checks should first check if active new rules for a given account exist in this table (and apply specified measures); if not, it should check the default rules to decide if a measure is required';
   1331 
   1332   CREATE INDEX legitimization_outcomes_active
   1333     ON legitimization_outcomes(h_payto)
   1334     WHERE is_active;
   1335 
   1336   CREATE TABLE legitimization_processes
   1337     (legitimization_process_serial_id BIGSERIAL UNIQUE
   1338     ,h_payto BYTEA NOT NULL CHECK (LENGTH(h_payto)=64)
   1339      REFERENCES wire_targets (wire_target_h_payto)
   1340     ,start_time INT8 NOT NULL
   1341     ,expiration_time INT8 NOT NULL DEFAULT (0)
   1342     ,legitimization_measure_serial_id INT8
   1343      REFERENCES legitimization_measures (legitimization_measure_serial_id)
   1344     ,measure_index INT4
   1345     ,provider_section TEXT NOT NULL
   1346     ,provider_user_id TEXT DEFAULT NULL
   1347     ,provider_legitimization_id TEXT DEFAULT NULL
   1348     ,redirect_url TEXT DEFAULT NULL
   1349     ,finished BOOLEAN DEFAULT (FALSE)
   1350     )
   1351     PARTITION BY HASH (h_payto);
   1352 
   1353   COMMENT ON TABLE legitimization_processes
   1354     IS 'here we track KYC processes we initiated with external providers; the main reason is so that we do not initiate a second process when an equivalent one is still active; note that h_payto, provider_section, jcontext must match and the process must not be finished or expired for an existing redirect_url to be re-used; given that clients may voluntarily initiate KYC processes, there may not always be a legitimization_measure that triggered the setup';
   1355   COMMENT ON COLUMN legitimization_processes.h_payto
   1356     IS 'foreign key linking the entry to the wire_targets table, NOT a primary key (multiple KYC setups are possible per wire target)';
   1357   COMMENT ON COLUMN legitimization_processes.start_time
   1358     IS 'when was the legitimization process initiated';
   1359   COMMENT ON COLUMN legitimization_processes.expiration_time
   1360     IS 'when does the process expire (and needs to be manually set up again)';
   1361   COMMENT ON COLUMN legitimization_processes.measure_index
   1362     IS 'index of the measure in legitimization_measures that was selected for this KYC setup; NULL if legitimization_measure_serial_id is NULL; enables determination of the context data provided to the external process';
   1363   COMMENT ON COLUMN legitimization_processes.provider_section
   1364     IS 'Configuration file section with details about this provider';
   1365   COMMENT ON COLUMN legitimization_processes.provider_user_id
   1366     IS 'Identifier for the user at the provider that was used for the legitimization. NULL if provider is unaware.';
   1367   COMMENT ON COLUMN legitimization_processes.provider_legitimization_id
   1368     IS 'Identifier for the specific legitimization process at the provider. NULL if legitimization was not started.';
   1369   COMMENT ON COLUMN legitimization_processes.legitimization_measure_serial_id
   1370     IS 'measure that enabled this setup, NULL if client voluntarily initiated the process';
   1371   COMMENT ON COLUMN legitimization_processes.redirect_url
   1372     IS 'Where the user should be redirected for this external KYC process';
   1373   COMMENT ON COLUMN legitimization_processes.finished
   1374     IS 'set to TRUE when the specific legitimization process is finished';
   1375 
   1376   CREATE TABLE kyc_attributes
   1377     (kyc_attributes_serial_id INT8 GENERATED BY DEFAULT AS IDENTITY
   1378     ,h_payto BYTEA PRIMARY KEY CHECK (LENGTH(h_payto)=32)
   1379      REFERENCES wire_targets (wire_target_h_payto)
   1380     ,legitimization_process_serial_id INT8
   1381      REFERENCES legitimization_processes (legitimization_process_serial_id)
   1382      DEFAULT NULL
   1383     ,collection_time INT8 NOT NULL
   1384     ,expiration_time INT8 NOT NULL
   1385     ,trigger_outcome_serial INT8 NOT NULL
   1386      REFERENCES legitimization_outcomes(outcome_serial_id)
   1387     ,encrypted_attributes BYTEA NOT NULL
   1388     ) PARTITION BY HASH (h_payto);
   1389 
   1390   COMMENT ON COLUMN kyc_attributes.h_payto
   1391     IS 'identifies the account this is about';
   1392   COMMENT ON COLUMN kyc_attributes.legitimization_process_serial_id
   1393     IS 'serial ID of the legitimization process that resulted in these attributes, NULL if the attributes are from a form directly supplied by the account owner via a form';
   1394   COMMENT ON COLUMN kyc_attributes.collection_time
   1395     IS 'when were these attributes collected';
   1396   COMMENT ON COLUMN kyc_attributes.expiration_time
   1397     IS 'when are these attributes expected to expire';
   1398   COMMENT ON COLUMN kyc_attributes.trigger_outcome_serial
   1399     IS 'ID of the outcome that was returned by the AML program based on the KYC data collected';
   1400   COMMENT ON COLUMN kyc_attributes.encrypted_attributes
   1401     IS 'encrypted JSON object with the attribute data the check provided';
   1402 
   1403   CREATE TABLE aml_history
   1404     (aml_history_serial_id INT8 GENERATED BY DEFAULT AS IDENTITY
   1405     ,h_payto BYTEA CHECK (LENGTH(h_payto)=32)
   1406      REFERENCES wire_targets (wire_target_h_payto)
   1407     ,outcome_serial_id INT8 NOT NULL
   1408      REFERENCES legitimization_outcomes (outcome_serial_id)
   1409     ,justification TEXT NOT NULL
   1410     ,decider_pub BYTEA CHECK (LENGTH(decider_pub)=32)
   1411     ,decider_sig BYTEA CHECK (LENGTH(decider_sig)=64);
   1412 
   1413   COMMENT ON TABLE aml_history
   1414     IS 'Records decisions by AML staff with the respective signature and free-form justification.';
   1415   COMMENT ON COLUMN aml_history.outcome_serial_id
   1416     IS 'Actual outcome for the account (included in what decider_sig signs over)';
   1417   COMMENT ON COLUMN aml_history.decider_sig
   1418     IS 'Signature key of the staff member affirming the AML decision; of type AML_DECISION';
   1419 
   1420   CREATE TABLE kyc_events
   1421     (kyc_event_serial_id INT8 GENERATED BY DEFAULT AS IDENTITY
   1422     ,event_timestamp INT8 NOT NULL
   1423     ,event_type TEXT NOT NULL);
   1424 
   1425   COMMENT ON TABLE kyc_events
   1426     IS 'Records of key events for statistics. Populated via triggers.';
   1427   COMMENT ON COLUMN kyc_events.event_type
   1428     IS 'Name of the event, such as account-open or sar-filed';
   1429 
   1430   CREATE INDEX kyc_event_index
   1431     ON kyc_events(event_type,event_timestamp);
   1432 
   1433 
   1434 The ``jmeasures`` JSON in the ``legitimization_measures``
   1435 table is of type `LegitimizationMeasures`.
   1436 
   1437 The ``jnew_rules`` JSON in the ``legitimization_outcomes``
   1438 table is of type `LegitimizationRuleSet`.
   1439 
   1440 The ``jproperties`` JSON in the ``legitimization_outcomes`` table is of
   1441 type `AccountProperties`.
   1442 
   1443 
   1444 KYC forms
   1445 ^^^^^^^^^
   1446 
   1447 The KYC SPA run by clients needs to support three TYPEs of checks. INFO is
   1448 only about displaying the provided information, LINK is about setting up an
   1449 exteral KYC check and redirecting there. FORM is about displaying a particular
   1450 (HTML) form to the user and POSTing the entered information directly with the
   1451 exchange.  Here we describe the forms that must be supported:
   1452 
   1453 * **CHOICE**: Asks the client a multiple-choice question.  The context must
   1454   include "choices: string[]" with a list of choices to show.  Used, for
   1455   example, to ask a client if they are an individual or a business.  The
   1456   resulting HTML FORM field name must be "choice" and it must be mapped to
   1457   strings from the choices list.
   1458 
   1459 * **UPLOAD**: Asks the client to upload a single file.
   1460   The context must include a ``validity_duration`` which
   1461   will be converted to the ``expiration_time`` for
   1462   the uploaded data.  The context may furthermore include
   1463   ``extensions?: string[]`` with a list of allowed file extensions the client's
   1464   file must end with (e.g. "png", "pdf", "gif").  In the absence of this
   1465   context, any file may be uploaded.  The context may also include a
   1466   ``size_limit?: Integer`` with the maximum file size in bytes that can be
   1467   uploaded.  The resulting HTTP POST should provide at least two fields, "filename" and
   1468   "filedata".  "filename" must be set to the basename of the original file (to
   1469   the extend that it is available), and "filedata" to the base64-encoding of
   1470   the uploaded data.
   1471 
   1472 As with other SPA checks, the KYC form should also show
   1473 the description of the check.
   1474 
   1475 
   1476 Merchant modifications
   1477 ^^^^^^^^^^^^^^^^^^^^^^
   1478 
   1479 A new setting is required where the merchant backend can be configured for a
   1480 business (default) or individual.
   1481 
   1482 We introduce new ``kyc_ok``, ``aml_decision``, ``kyc_timestamp`` and
   1483 ``exchange_kyc_serial`` fields into a new table ``merchant_kyc`` with primary
   1484 keys ``exchange_url`` and ``account_serial``.  This status is updated whenever
   1485 a deposit is created or tracked, or whenever the mechant backend receives a
   1486 ``/kyc-check/`` response from the exchange.  Initially,
   1487 ``exchange_kyc_serial`` is zero, indicating that the merchant has not yet made
   1488 any deposits and thus does not have an account at the exchange.
   1489 
   1490 A new private endpoint ``/kyc`` is introduced which allows frontends to
   1491 request the ``/kyc`` status of any configured account (including with long
   1492 polling).  If the KYC status is negative or the ``kyc_timestamp`` not recent
   1493 (say older than one month), the merchant backend will re-check the KYC status
   1494 at the exchange (and update its cached status).  The endpoint then returns
   1495 either that the KYC is OK, or information (same as from the exchange endpoint)
   1496 to begin the KYC process.
   1497 
   1498 The merchant backend uses the new field to remember that a KYC is pending
   1499 (after detection in ``taler-merchant-depositcheck``) and the SPA then shows a
   1500 notification whenever the staff is logged in to the system.  The notification
   1501 can be hidden for the current day (remembered in local storage).
   1502 
   1503 The notification links to a (new) KYC status page. When opened, the KYC SPA
   1504 first re-checks the KYC status with the exchange.  If the KYC is still
   1505 unfinished, that SPA will show forms, links or contact information to begin
   1506 the KYC process (for example, redirecting to the OAuth 2.0 login page of the
   1507 legitimization resource server), otherwise it shows that the KYC process is
   1508 done. If the KYC is unfinished, the merchant SPA should use long-polling on
   1509 the KYC status on this page to ensure it is always up-to-date, and change to
   1510 ``KYC satisfied`` should the long-poller return with positive news.
   1511 
   1512 .. note::
   1513 
   1514    Semi-related: The TMH_setup_wire_account() is changed to use
   1515    128-bit salt values (to keep ``deposits`` table small) and checks for salt
   1516    to be well-formed should be added "everywhere".
   1517 
   1518 
   1519 
   1520 Bank requirements
   1521 ^^^^^^^^^^^^^^^^^
   1522 
   1523 The exchange primarily requires a KYC provider to be operated by the
   1524 bank that offers an endpoint for with an API implemented by one of
   1525 the logic plugins (and the respective legitimization configuration).
   1526 
   1527 
   1528 Logic plugins
   1529 ^^^^^^^^^^^^^
   1530 
   1531 The ``$PROVIDER_SECTION`` is based on the name of the configuration section,
   1532 not on the name of the logic plugin (that we call ``$LOGIC``).  Using the
   1533 configuration section, the exchange then determines the logic plugin to use.
   1534 
   1535 This section describes the general API for all of the supported KYC providers,
   1536 as well as some details of how this general API could be implemented by the
   1537 logic for different APIs.
   1538 
   1539 
   1540 General KYC Logic Plugin API
   1541 ----------------------------
   1542 
   1543 This section provides a sketch of the proposed API for the KYC logic plugins.
   1544 
   1545 * initiation of KYC check (``kyc-check``):
   1546 
   1547   - inputs:
   1548     + provider_section (for additional configuration)
   1549     + h_payto
   1550   - outputs:
   1551     + success/provider-failure
   1552     + redirect URL (or NULL)
   1553     + provider_user_id (or NULL)
   1554     + provider_legitimization_id (or NULL)
   1555 
   1556 * KYC status check (``kyc-proof``):
   1557 
   1558   - inputs:
   1559     + provider_section (for additional configuration)
   1560     + h_payto
   1561     + provider_user_id (or NULL)
   1562     + provider_legitimization_id (or NULL)
   1563   - outputs:
   1564     + success/pending/user-aborted/user-failure/provider-failure status code
   1565     + HTML response for end-user
   1566 
   1567 * Webhook notification handler (``kyc-webhook``):
   1568 
   1569   - inputs:
   1570     + HTTP method (GET/POST)
   1571     + rest of URL (after provider_section)
   1572     + HTTP body (if applicable!)
   1573   - outputs:
   1574     + success/pending/user-aborted/user-failure/provider-failure status code
   1575     + h_payto (for DB status update)
   1576     + HTTP response to be returned to KYC provider
   1577 
   1578 The plugins do not directly interact with the database, the caller sets the
   1579 expiration on ``success`` and also updates ``provider_user_id`` and
   1580 ``provider_legitimization_id`` in the tables as required.
   1581 
   1582 
   1583 For the webhook, we need a way to lookup ``h_payto`` by other data, so the
   1584 KYC logic plugin API should be provided a method lookup with:
   1585 
   1586 - inputs:
   1587 
   1588   + ``provider_section``
   1589   + ``provider_legitimization_id``
   1590 - outputs:
   1591 
   1592   + ``h_payto``
   1593   + ``legitimization_process_row``
   1594 
   1595 
   1596 OAuth 2.0 specifics
   1597 -------------------
   1598 
   1599 In terms of configuration, the OAuth 2.0 logic requires the respective client
   1600 credentials to be configured apriori to enable access to the legitimization
   1601 service.
   1602 
   1603 For the ``/kyc-check/`` endpoint, the OAuth 2.0 logic may need to create and
   1604 store a nonce to be used during ``/kyc-proof/``, depending on the OAuth
   1605 variant used.  This may require another exchange table.  The OAuth 2.0 process
   1606 must then be set up to end at the new ``/kyc-proof/$PROVIDER_ID/`` endpoint.
   1607 
   1608 This ``/kyc-proof/oauth2/`` endpoint must query the OAuth 2.0 server using the
   1609 ``code`` argument provided as a query parameter. Based on the result, it then
   1610 updates the KYC table of the exchange with the legitimization status and
   1611 returns a human-readable KYC status page.
   1612 
   1613 The ``/kyc-webhook/`` is not applicable.
   1614 
   1615 
   1616 Persona specifics
   1617 -----------------
   1618 
   1619 We would use the hosted flow. Endpoints return a ``request-id``, which we should
   1620 log for diagnosis.
   1621 
   1622 For ``/kyc-check/``:
   1623 
   1624 * Post to ``/api/v1/accounts`` using ``reference-id`` set to our ``h_payto``.
   1625   Returns ``id`` (account_id).
   1626 
   1627 * Create ``/verify`` endpoint using ``template-id`` (from configuration),
   1628   and ``account_id`` (from previous step) and a ``reference-id`` (use
   1629   the ``legitimization_serial_id`` for the new process). Set
   1630   ``redirect-uri`` to ``/kyc-proof/$PROVIDER_ID/``.  However, we cannot
   1631   rely on the user clicking this, so we must also configure a webhook.
   1632   The request returns a '``verification-id``.  That we store under
   1633   the ``provider_legitimization_id`` in the database.
   1634 
   1635 For ``/kyc-proof/``:
   1636 
   1637 * Use the ``/api/v1/verifications`` endpoint to get the verification
   1638   status. Requires the ``verification-id`` from the previous step.
   1639   Results include: created/pending/completed/expired (aborted)/failed.
   1640 
   1641 For ``/kyc-webhook/``:
   1642 
   1643 * The webhook is authenticated using a shared secret, which should
   1644   be in the configuration.  So all we should have to do is parse
   1645   the POSTed body to find the status and the ``verification-id`` to
   1646   lookup ``h_payto`` and return the result.
   1647 
   1648 
   1649 KYC AID specifics
   1650 -----------------
   1651 
   1652 For ``/kyc-check/``:
   1653 
   1654 * Post to ``/applicants`` with a type (person or company) to
   1655   obtain ``applicant_id``. Store that under ``provider_user_id``.
   1656   ISSUE: *we* need to get the company_name, business_activity_id
   1657   and registration_country before this somehow!
   1658 
   1659 * start with create form URL ``/forms/$FORM_ID/urls``
   1660   providing our ``h_payto`` as the ``external_applicant_id``,
   1661   using the ``applicant_id`` from above,
   1662   and the ``/kyc-proof/$PROVIDER_ID`` for the ``redirect_url``.
   1663 
   1664 * redirect customer to the ``form_url``,
   1665   store the ``verification_id`` under ``provider_legitimization_id``
   1666   in the database.
   1667 
   1668 For ``/kyc-proof/``:
   1669 
   1670 * Not needed, just return an error.
   1671 
   1672 For ``/kyc-webhook/``:
   1673 
   1674 * For security, we should probably simply trigger the GET on
   1675   ``/verifications/{verification_id}`` to not trust an unsigned POST
   1676   to tell us anything for sure.  The result is then returned.
   1677 
   1678 
   1679 Types of KYC events
   1680 ^^^^^^^^^^^^^^^^^^^
   1681 
   1682 The ``/aml/$OFFICER_PUB/kyc-statistics`` endpoint exposes statistics for
   1683 various KYC event types.
   1684 
   1685 We will initially support the use of the following types of KYC events in the
   1686 SPA (and have a dialog to show the total number of any of these for any
   1687 specified time range):
   1688 
   1689 * account-open
   1690 * account-closed
   1691 * voluntary-sar
   1692 * mandatory-sar
   1693 * pep-started
   1694 * pep-ended
   1695 * risky-started
   1696 * risky-ended
   1697 * account-frozen
   1698 * account-unfrozen
   1699 
   1700 Based on these, the SPA should also be albe to show active
   1701 statistics (for any given timestamp) on the total number of:
   1702 
   1703 * open accounts
   1704 * frozen accounts
   1705 * high-risk accounts
   1706 * PEPs served
   1707 
   1708 .. note::
   1709 
   1710    This can be done by simply running the queries with
   1711    a start time of zero and subtracting.
   1712 
   1713 
   1714 Alternatives
   1715 ============
   1716 
   1717 We could also store the access token (returned by OAuth 2.0), but that seems
   1718 slightly more dangerous and given the close business relationship is
   1719 unnecessary. Furthermore, not all APIs offer this.
   1720 
   1721 We could extend the KYC logic API to return key attributes about the user
   1722 (such as legal name, phone number, address, etc.) which we could then sign and
   1723 return to the user.  This would be useful in P2P payments to identify the
   1724 origin of an invoice.  However, we might want to be careful to not disclose
   1725 the key attributes via the API by accident.  This could likely be done by
   1726 limiting access to the respective endpoint to messages with a signature by the
   1727 reserve private key (which is the only case where we care to certify things
   1728 anyway).
   1729 
   1730 
   1731 Drawbacks
   1732 =========
   1733 
   1734 
   1735 Discussion / Q&A
   1736 ================
   1737 
   1738 (This should be filled in with results from discussions on mailing lists / personal communication.)
   1739 
   1740 
   1741 If you have questions, remarks or suggestions regarding this information,
   1742 please feel free to leave a comment at our
   1743 `TALER Integration Community Hub <https://ich.taler.net/t/gnu-taler-exchange-documentation/78>`_.