taler-docs

023-taler-kyc.rst (73207B)

---

 DD 23: Taler KYC
 ################
 
 Summary
 =======
 
 This document discusses the Know-your-customer (KYC) and Anti-Money Laundering
 (AML) processes supported by Taler.
 
 
 Motivation
 ==========
 
 To legally operate, Taler has to comply with KYC/AML regulation that requires
 banks to identify parties involved in transactions at certain points.
 
 
 Requirements
 ============
 
 Taler needs to take *measures* based on the following primary *triggers*:
 
 * Customer withdraws money over a monthly threshold
 
   * exchange triggers KYC
   * key: IBAN (encoded as payto:// URI)
 
 * Wallet receives (via refunds) money resulting in a balance over a threshold
 
   * this is a client-side restriction
   * key: reserve (=KYC account) long term public key per wallet (encoded as payto:// URI)
 
 * Wallet receives money via P2P payments
 
   * there are two sub-cases: PUSH and PULL payments
   * key: reserve (=KYC account) long term public key per wallet (encoded as payto:// URI)
 
 * Merchant receives money (Q: any money, or above a monthly threshold?)
 
   * key: IBAN (encoded as payto:// URI)
 
 * Reserve is "opened" for invoicing.
 
   * key: reserve (=KYC account) long term public key per wallet (encoded as payto:// URI)
 
 * Import of new sanctions lists and triggering of measures against matches of existing
   customer records against the list
 
 For the different operation types, there can be both soft and hard
 limits. Soft limits are those that the customer may raise by providing data
 and passing KYC checks.  Hard limits cannot be lifted, for example because an
 exchange forbids crossing those limits in its terms of service for all
 customers.
 
 
 Process requirements
 ^^^^^^^^^^^^^^^^^^^^
 
 The key consideration here is *plausibilization*: staff needs to
 check that the client-provided information is plausible. As this
 is highly case-dependent, this cannot be automated.
 
 For the different *measures*, there are various different possible KYC/AML
 *checks* that could happen:
 
 * In-person validation by AML staff
 * Various forms to be filled by AML staff
 * Validation involving local authorities and post-office
 * Online validation, sometimes with multiple options (like KYC for multiple people):
 
   * Forms to be supplied by user (different types of ID)
   * Interactive video
   * Documents to be supplied (business register)
   * Address validation (e-mail or phone or postal)
 
 Additionally, the process is dynamic and conditional upon various decisions:
 
 * Individual vs. business
 * PEP or non-PEP
 * Hit on sanctions list
 * Type of business (trust, foundation, listed on stock market, etc.)
 * Need for plausibilization (via documents by user or staff research)
 * Periodic updates (of customer data, of sanction lists) and re-assessment
 
 There are also various *outcomes*:
 
 * normal operation (with expiration date)
 * normal operation but with AML staff investigating (new measure)
 * held, requesting customer documentation (new measure)
 * held, AML staff reviewing evidence for plausibilization (new measure)
 * automatically frozen until certain day (due to sanctions)
 * institutionally frozen until certain day (due to order by state authority)
 * operation is categorically not allowed (at least above certain limits)
 
 Outcomes may also be (partially) public, that is exposed to the client. For
 example, we may want to tell a wallet that it has hit a hard withdraw limit,
 but might succeed at withdrawing a smaller amount.
 
 The outcome of a *check* can set new rules or trigger another *measure* (the
 latter is conditional on reaching the expiration time of the outcome).
 
 As a result, we largely end up in a large state machine where the AML staff has
 serious flexibiltiy while the user needs guidance as to the possible next moves
 and/or to the current state of their account (where some information must not be
 disclosed).
 
 
 Documentation requirements
 ^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 For each account we must:
 
 * define risk-profile (902.4, 905.1)
 * document the specific setup, likely not just the INI file
 * should have some key Anti-Money-Laundering Act (AMLA)
   file attributes, such as:
 
   * File opened, file closed (keep data for X years afterwards!)
   * low-risk or high-risk business relationship
   * PEP status
   * business domain
   * authority notification dates (possibly multiple) with
     voluntary or mandatory notification classification
 
 Finally, we need to produce statistics:
 
 * There must be a page with an overview of AMLA files with opening
   and closing dates and an easy way to determine for any day the
   number of open AMLA files
 * Technically, we also need a list of at-risk transactions and of
   frozen transactions, but given that we can really only freeze
   on an account-basis, I think there is nothing to do here
 * number of incidents reported (voluntarily, required)
 * number of business relationships at any point in time
 * number of risky business relationships (PEP, etc.)
 * number of frozen transactions (authority vs. sanction) with start-date and end-date
 * start-data and end-date of relationships (data retained for X years after end of relationship)
 
 For this high-level monitoring, we need certain designated critical events to
 be tracked in the system statistics:
 
 * account opened
 * set to high risk
 * set to low risk
 * suspicious activity report filed with authority
 * account frozen
 * account unfrozen
 * account closed
 * sanction list import / update
 
 
 TODO: Sanction lists
 ^^^^^^^^^^^^^^^^^^^^
 
 We need to be able to import new sanction lists (whenever they are published)
 and then check existing AMLA files against those lists.  Additionally, newly
 created AMLA files must be checked against the current list and some "measure"
 applied in case of a match.
 
 This will primarily require us to define an endpoint to upload a sanction list
 and to define a new table to track the list of sanctioned entities.  As it is
 expected that sanction lists will not permit fully automated determinations in
 all cases, an external "sanction check" program should be configured which
 compares records against the current list and determines the correct measure,
 such as no change, further manual review by AML staff, or even automatic
 freeze (and report) depending on how well the records match.
 
 Basically, the "sanction check" program takes the sanction list and an
 attribute set to compute the same kind of `AmlOutcome` that an AML program
 outputs given a context and an attribute set.
 
 
 Security requirements
 ^^^^^^^^^^^^^^^^^^^^^
 
 IBANs are predictable. We (probably) do not want random people to be able to
 initate KYC processes for other parties. Similarly, the attestation API
 requires us to somehow *authenticate* the user to ensure we only give out
 attestation data to the data subject themselves. For P2P payments and
 withdrawals, we have the reserve public key that is only known to the data
 subject and thus can be used to authenticate the client via a signature. Only
 pure deposits (by merchants or directly from a wallet) are a problem as the
 only thing we know about the receiver is the IBAN at that time, and literally
 any user could just deposit money into some bank account, so knowledge of the
 IBAN is insufficient to determine that we actually are communicating with the
 owner of the bank account.
 
 
 Further considerations
 ^^^^^^^^^^^^^^^^^^^^^^
 
 On top of all of this, we need to plan some *diagnostics* to determine when
 components fail (such as scripts or external services providing malformed
 results).
 
 Optionally, in the future, the solution should support fees to be paid by the
 user for *voluntary* KYC processes related to attestation (#7365).
 
 
 Proposed Solution
 =================
 
 The main state of an account is represented by a set of `KYC rules <KycRule>` (the
 `LegitimizationRuleSet`) which specify the current *rules* to apply to
 transactions involving the account. Rules can *exposed* to the account owner,
 or can be secret.  Each *rule* specifies certain *conditions* which, if met,
 *trigger* a set of *measures*.  After a *rule* was *triggered* and
 before the *outcome* of a respective *measure* has been produced (say
 because the user did not yet enter their data or the AML officer is still
 reviewing the case), the existing rules remain in force. Rules have a display
 priority, and if a second rule with a higher display priority is also
 triggered, the *measures* of the higher-priority rule become the active
 *measures*.  Except for the default rule set, every legitimization rule set
 also has an *expiration* time after which a successor *measure* (or the
 default rule set) is automatically triggered.
 
 For any possible *measures*, we define:
 
 * Contextual input data to be provided (with dynamic inputs,
   e.g. amount set dynamically based on the *trigger* could be
   in the context)
 * A *check* to be performed (checks can be user-interactive (LINK, FORM)
   or staff-interactive (INFO))
 * A fallback *measure* to take on failure of a user-interactive check
   (if the check fails, we cannot run the AML *program* as required inputs
   might be missing!)
 * An (AML) *program* that uses *attribtes* from the *check* as well as
   *context* data to determine an *outcome* represented as the
   `AmlOutcome`.
 
 "verboten" is the name of a special *measure*, which means that crossing the
 respective transaction threshold is categorically not allowed (for this
 account).  "verboten" with a threshold of zero can be used to freeze funds.
 
 Possible *outcomes* of a measure include:
 
 * The next operational state (normal, AML investigation) of the account
   (basically, whether to add it to the work list of AML staff).
 * A new set of *rules* in the form of a `LegitimizationRuleSet` that
   determines custom rules to apply to transactions involving the account;
   such rules may be used to block certain transactions by using the
   "verboten" measure.  The `LegitimizationRuleSet` also must specify
   an *expiration* time by which we fall back to a successor measure
   *or* to the default rules.
 * A (largely) free-form set of `AccountProperties` that AML staff can
   use to tag accounts with. Some default properties are defined, but
   the exchange does not do anything with these and AML SPAs are free to
   use any properties they like.  Account properties are only exposed
   to AML staff and never to the customer.
 * A set of *events* that are to be added to the timeline of the
   operator for statistical purposes.
 
 For the user-interactive *checks* we need a KYC SPA that is given:
 
 * instructions to render (with either a form to fill or links to external checks);
   here the context could provide an array of choices!
 * possibly an external check that was set up (if any); for cost-reasons, we
   should only do one at a time, and probably should then always redirect the
   browser to that check.
 
 For the staff-interactive *checks* we need an AML SPA:
 
 * to file forms and upload documentation (without state transition)
 * to decide on next measure (providing context); here, the exchange needs
   to expose the list of available *measures* and required *context* for each
 
 We need some customer-driven interactivity in KYB/KYC process, for example the
 user may need to be given choices (address vs. phone, individual vs. business,
 order in which to provide KYC data of beneficiaries). As a result, the
 exchange needs to serve some SPA for *measures* where the user is shown the
 next step(s) or choices (which person to collect KYC data on, whether to run
 challenger on phone number of physical address, etc.).  The SPA should also
 potentially contain a form to allow the customer to directly upload documents
 to us (like business registration) instead of to some KYC provider. This is
 because KYC providers may not be flexible enough.  The SPA should also allow
 the customer to perform KYC checks voluntarily.
 
 Similarly, the AML staff will need to be able to trigger rather complex
 KYB/KYC processes, like "need KYC on X and Y and Z" or "phone number or
 mailing address" or "please upload form A/T/S".  Here in particular it
 should be possible to request not only filled forms, but arbitrary
 documents.
 
 
 Terminology
 ^^^^^^^^^^^
 
 * **Attributes**: Attributes are used to represent KYC data obtained about
   an account holder. Attributes include passport images, address data,
   business registration documents, and indeed arbitrary forms filed by
   AML staff or the customer themselves.  Attribute data is considered
   sensitive private information and is thus stored encrypted within the
   exchange database.
 
 * **Check**: A check establishes a particular attribute of a user, such as
   their name based on an ID document and lifeness, mailing address, phone
   number, taxpayer identity, etc.  Checks may be given *context* (such as
   whether a customer is an individual or a business) to run correctly. Checks
   can also be AML staff inserting information for plausibilization.  Checks
   result in *attributes* about the account's owner which are given to an
   external AML *program* together with the *context* to determine an *outcome*.
   KYC checks are always specified with a fallback *measure* to be taken if
   the check fails.
 
 * **Condition**: A condition specifies when KYC is required. Conditions
   include the *type of operation*, a threshold amount (e.g. above EUR:1000)
   and possibly a time period (e.g. over the last month).
 
 * **Configuration**: The configuration determines the *legitimization rules*,
   and specifies which providers offer which *checks*.
 
 * **Context**: Context is information provided as input into a *check* and
   *program* to customize their execution. The context is initially set by the
   *measure* (possibly including data from the *trigger*).  Naturally, the
   *program* may use its `AmlProgramInput` which includes *context* and
   *attribute* data to compute an update *context* for the next set of
   *measures* that it specifies in the `LegitimizationRuleSet` as part
   of the `AmlOutcome`.  Thus, *context* is something that typically
   evolves as the *account* undergoes *measures*.  Context is lost if
   an account transitions to default *legitimization rules* due to
   *expiration*.
 
 * **Display priority**: Every rule has a *display priority*. If a second
   *rule* is *triggered* before the *outcome* of a *rule* could be determined,
   the *rule* with the larger *display priority* becomes the requirement that
   the account owner has to satisfy (and that thus will be displayed by the
   KYC SPA).
 
 * **Expiration**: Except for the default rules, any set of KYC rules is
   subject to *expiration*. This can be because *attributes* become outdated or
   because sanctions have a time limit. The expiration time thus determines
   when a new *measure* is triggered in the absence of a transaction crossing
   thresholds in the current set of *legtimization rules*.
 
 * **Legitimization rules**: The *legitimization rules* determine under which
   *conditions* which *measures* will be taken. A `LegitimizationRuleSet`
   always also includes an *expiration* time period for (custom, non-default)
   *legitimization rules* after which a fallback measure* will automatically
   apply.  Legitimization rules may be *exposed* to the client (for example,
   to allow a wallet to stay below hard withdraw thresholds) or could be secret.
 
 * **Logic**: Logic refers to a specific bit of code (realized as an exchange
   plugin) that enables the interaction with a specific *provider*.  Logic
   typically requires *configuration* for access control (such as an
   authorization token) and possibly the endpoint of the specific *provider*
   implementing the respective API.
 
 * **Measure**: Describes the possible outgoing edges from one state in the
   state machine (including how to show the current state). Each edge is given
   some *context* and a *check* to be performed as well as an AML *program*
   which determines the *outcome*.  We generally distinguish between
   "original" measures (defined globally in the exchange configuration) and
   "custom" measures (defined specifically for an account by AML staff).
 
 * **Outcome**: An `AmlOutcome` describes the account state that an account
   ends up in due to either an AML staff action or an AML *program* doing some
   computation over the attributes resulting from a *check*.  Outcomes can be
   that certain types of transactions are "verboten", that the account is (or
   remains) under investigation by AML staff, that the account is given certain
   properties, and/or that certain events are to be logged. Outcomes also
   include a new set of *legitimization rules* to apply (and an *expiration*
   time at which point a successor *measure* will be automatically taken).
 
 * **Provider**: A provider performs a specific set of *checks* at a certain
   *cost*. Interaction with a provider is performed by provider-specific
   *logic*.
 
 * **Program**: An AML helper *program* is given *context* about the current
   state of an account and the attribute data from a *check* to compute the
   *outcome*.  For example, a *program* may look at the "PEP" field of a KYC
   check and decide if the outcome is to put the account into ``normal`` or
   ``held-for-manual-review`` state.  AML programs are always specified
   with a fallback *measure* to be taken if the program fails.
 
 * **Trigger**: A specific transaction that satisfies a **Condition**.
 
 * **Type of operation**: The operation type determines which Taler-specific
   operation has triggered the KYC requirement. We support four types of
   operation: withdraw (by customer), deposit (by merchant), P2P receive (by
   wallet) and (high) wallet balance.
 
 
 Account owner authentication
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Access to the KYC SPA (or rather, its account-specific state) is controlled by
 a *target token* (which is effectively like a bearer token, except passed
 inside the URL).  The *target token* ensures that only the account owner has
 access to the KYC processes.  It can be obtained by authenticating using
 either the merchant private key or reserve private key, depending on the type
 of the account (IBAN or wallet-reserve respectively).
 
 When we need to authenticate a bank account owner, we will simply require them
 to make an outgoing wire transfer into the exchange bank account with a public
 key in the wire transfer subject (just like when withdrawing), but augmented
 with the string "KYC" so we can distinguish the wire transfer from a regular
 withdrawal. Typically, we would put the merchant public key into the wire
 transfer subject; wallets MAY put their long-term reserve public key instead.
 The amount to be transferred is the *KYC fee*.
 
 This has several advantages:
 
 * Only the account owner can provide us with the public key, so we already
   have also one super-hard piece of KYC evidence.
 * If the account owner looses their public key, it's not a problem: they
   would just have to do the transfer again with a new key. No need for
   us to do any kind of intervention for key management.
 * We could theoretically get paid to do the KYC process, or just "charge" a
   nominal amount.
 * This also somewhat addresses the payment for voluntary KYC processes where
   a merchant wants to do KYC to get us to attest their identity for their
   customers even if we do not yet have a legal need.  The only issue here
   is that this does not work if voluntary KYC is invoiced while mandatory
   KYC is gratis. But, that kind of configuration is a business decision
   and there is no hard need to support it immediately.
 * This definitively addresses the need for authentication to access the
   attestation API, which so far was only available for P2P payments as
   we could not authenticate merchants.
 * The "KYC" string allows us to distinguish the authentication transfers from
   withdrawal transfers; by keeping the KYC fee at or below the closing fee,
   we can even deploy this without fully updating the logic everywhere to
   distinguish KYC transfers
 
 
 451 Response
 ^^^^^^^^^^^^
 
 When KYC operations are required, various endpoints may respond with a
 ``451 Unavailable for Legal Reasons`` status code and a `LegitimizationNeededResponse`
 body.
 
 New endpoints
 ^^^^^^^^^^^^^
 
 .. http:get:: /kyc-check/$H_PAYTO
 
   Checks the KYC status of a particular payment target and possibly begins a
   KYC process by allowing the customer to choose the next KYC measure to
   satisfy. This endpoint is typically used by wallets or merchants that
   have been told that a transaction is not happening because it triggered
   some KYC/AML measure and now want to check how the KYC/AML
   requirement could be fulfilled (or whether it already has been
   statisfied and the operation can now proceed).  Long-polling may be used
   to instantly observe a change in the KYC requirement status.
 
   The payto hash of the ``/kyc-check/`` endpoint encodes the
   account (or wallet) for which legitimization measures are determined.
   It is returned in `LegitimizationNeededResponse` responses as in
   the case of withdraw, the wallet may not know the debited bank account.
 
   Given a valid pair of payto hash and account owner signature, the
   ``/kyc-check/`` endpoint returns either just the KYC status or redirects the
   client (202) to the next required stage of the KYC process.  The redirection
   must be for an HTTP(S) endpoint to be triggered via a simple HTTP GET.  It
   must always be the same endpoint for the same client, as the wallet/merchant
   backend are not required to check for changes to this endpoint.  Clients
   that received a 202 status code may repeat the request and use long-polling
   to detect a change of the HTTP status.
 
   **Request:**
 
   *Account-Owner-Signature*:
 
     The client must provide Base-32 encoded EdDSA signature with
     ``$ACCOUNT_PRIV``, affirming the desire to obtain KYC data.  Note that
     this is merely a simple authentication mechanism, the details of the
     request are not protected by the signature.  The ``$ACCOUNT_PRIV`` is
     either the (wallet long-term) reserve private key or the merchant instance
     private key.
 
   :query timeout_ms=NUMBER: *Optional.*  If specified, the exchange will
     wait up to ``timeout_ms`` milliseconds if the requirement continues
     to be mandatory provisioning of KYC data by the client.
     Ignored if the HTTP status code is already ``200 Ok``.  Note that
     clients cannot long-poll for AML staff actions, so status information
     about an account being under AML review needs to be requested
     periodically.
 
   **Response:**
 
   :http:statuscode:`200 Ok`:
     No mandatory KYC actions are required by the client at this time.
     The client *may* still visit the KYC URL to initiate voluntary checks.
     The response will be an `AccountKycStatus` object which specifies
     restrictions that currently apply to the account. If the
     client attempts to exceed *soft* limits, the status may change
     to a ``202 Accepted``.  Hard limits cannot be lifted by passing KYC checks.
   :http:statuscode:`202 Accepted`:
     The account holder performed an operation that would have crossed
     *soft* limits and must be redirected to the provided location to perform
     the required KYC checks to satisfy the legal requirements. Afterwards, the
     ``/kyc-check/`` request should be repeated to check whether the
     user has completed the process.
     The response will be an `AccountKycStatus` object.
   :http:statuscode:`204 No content`:
     The exchange is not configured to perform KYC and thus
     the legal requirements are already satisfied.
   :http:statuscode:`403 Forbidden`:
     The provided signature is not acceptable for the payto hash.
   :http:statuscode:`404 Not found`:
     The requirement row is unknown.
 
 .. http:get:: /aml-spa/$FILENAME
 
   Serves the resources of the AML SPA.
 
 .. http:get:: /kyc-spa/$FILENAME
 
   Serves the resources of the KYC SPA. Note that
   ``$FILENAME`` must be syntactically distinct from
   the access token.  Any ``$ACCESS_TOKEN`` will be
   mapped internally to "index.html".
 
 .. http:get:: /kyc-spa/$ACCESS_TOKEN
 
   A set of ``/kyc-spa/$ACCESS_TOKEN`` GET endpoints is created per account
   hash that serves the KYC SPA.  This is where the ``/kyc-check/`` endpoint
   will in principle redirect clients.  The KYC SPA will use the
   ``$ACCESS_TOKEN`` of its URL to initialize itself via the
   ``/kyc-info/$ACCESS_TOKEN`` endpoint family.  The KYC SPA may download
   additional resources via ``/kyc-spa/$FILENAME``. The filenames must not
   match base32-encoded 256-bit values.
 
 .. http:get:: /kyc-info/$ACCESS_TOKEN
 
   The ``/kyc-info/$ACCESS_TOKEN`` endpoints are created per client
   account hash (but access controlled via a unique target token)
   to return information about the state of the KYC or AML process
   to the KYC SPA.  The SPA uses this information to show the user an
   appropriate dialog. The SPA should also long-poll this endpoint for changes
   to the AML/KYC state. Note that this is a client-facing endpoint, so it will
   only provide a restricted amount of information to the customer (as some
   laws may forbid us to inform particular customers about their true status).
   The endpoint will typically inform the SPA about possible choices to
   proceed, such as directly uploading files, contacting AML staff, or
   proceeding with a particular KYC process at an external provider (such as
   Challenger).  If the user chooses to initate a KYC process at an external
   provider, the SPA must request the respective process to be set-up by the
   exchange via the ``/kyc-start/`` endpoint.
 
   **Request:**
 
   *If-None-Match*:
     The client MAY provide an ``If-None-Match`` header with an ETag.
 
   :query timeout_ms=MILLISECONDS:
     *Optional.* If specified, the exchange will wait up to MILLISECONDS for
     a change to a more recent legitimization measure before returning a 304
     Not Modified status.
 
   **Response:**
 
   *Etag*: Will be set to the serial ID of the measure. Used for long-polling (only for 200 OK responses).
 
   :http:statuscode:`200 OK`:
     The body is a `KycProcessClientInformation`.
   :http:statuscode:`204 No Content`:
     There are no open KYC requirements or possible voluntary checks
     the client might perform.
   :http:statuscode:`304 Not Modified`:
     The KYC requirements did not change.
 
 
 .. http:post:: /kyc-upload/$ID
 
   The ``/kyc-upload/$ID`` POST endpoint allows the SPA to upload
   client-provided evidence.  The ``$ID`` will be provided as part of the
   ``/kyc-info`` body.  This is for checks of type ``FORM``.  In practice,
   ``$ID`` will encode both the ``$ACCESS_TOKEN`` and the index of the selected
   measure (but this should be irrelevant for the client).
 
   **Request:**
 
   Basically oriented along the possible formats of a HTTP form being
   POSTed. Details will depend on the form. The server will try to decode the
   uploaded body from whatever format it is provided in.
 
   **Response:**
 
   :http:statuscode:`204 No Content`:
     The information was successfully uploaded. The SPA should fetch
     an updated ``/kyc-info/``.
   :http:statuscode:`404 Not Found`:
     The ``$ID`` is unknown to the exchange.
   :http:statuscode:`409 Conflict`:
     The upload conflicts with a previous upload.
   :http:statuscode:`413 Request Entity Too Large`:
     The body is too large.
 
 .. http:post:: /kyc-start/$ID
 
   The ``/kyc-start/$ID`` POST endpoint allows the SPA to set up a new external
   KYC process. It will return the URL that the client must GET to begin the
   KYC process. The SPA should probably open this URL in a new window or tab.
   The ``$ID`` will be provided as part of the ``/kyc-info`` body.  In
   practice, ``$ID`` will encode both the ``$ACCESS_TOKEN`` and the index of
   the selected measure (but this should be irrelevant for the client).
 
   **Request:**
 
   Use empty JSON body for now.
 
   **Response:**
 
   :http:statuscode:`200 Ok`:
     The KYC process was successfully initiated. The URL is in a
     `KycProcessStartInformation` object.
 
   :http:statuscode:`404 Not Found`:
     The ``$ID`` is unknown to the exchange.
 
   .. note::
 
     As this endpoint is involved in every KYC check at the beginning, this
     is also the place where we could integrate the payment process for the KYC fee
     in the future (since **vATTEST**).
 
 
 .. http:get:: /kyc-proof/$PROVIDER_SECTION?state=$H_PAYTO
 
   Upon completion of the process at the external KYC provider, the provider
   must redirect the client (browser) to trigger a GET request to a new
   ``/kyc-proof/$H_PAYTO/$PROVIDER_SECTION`` endpoint.  Once this endpoint is
   triggered, the exchange will pass the received arguments to the respective
   logic plugin.  The logic plugin will then (asynchronously) update the KYC
   status of the user.  The logic plugin should redirect the user to the KYC
   SPA. This endpoint deliberately does not use the ``$ACCESS_TOKEN`` as the
   external KYC provider should not learn that token.
 
   This endpoint is thus accessed from the user's browser at the *end* of a KYC
   process, possibly providing the exchange with additional credentials to
   obtain the results of the KYC process.  Specifically, the URL arguments
   should provide information to the exchange that allows it to verify that the
   user has completed the KYC process. The details depend on the logic, which
   is selected by the "$PROVIDER_SECTION".
 
   While this is a GET (and thus safe, and idempotent), the operation may
   actually trigger significant changes in the exchange's state.  In
   particular, it may update the KYC status of a particular payment target.
 
   **Request:**
 
   Details on the request depend on the specific KYC logic that was used.
 
   If the KYC plugin logic is OAuth 2.0, the query parameters are:
 
   :query code=CODE:
      OAuth 2.0 code argument.
   :query state=STATE:
      OAuth 2.0 state argument with the H_PAYTO.
 
   .. note::
 
     Depending on the OAuth variant used, additional
     query parameters may need to be passed here.
 
   **Response:**
 
   Given that the response is returned to a user using a browser and **not** to
   a Taler wallet, the response format is in human-readable HTML and not in
   machine-readable JSON.
 
   :http:statuscode:`302 Found`:
     The KYC operation succeeded and the
     payment target is now authorized to transact.
     The browser is redirected to a human-readable
     page configured by the exchange operator.
   :http:statuscode:`401 Unauthorized`:
     The provided authorization token is invalid.
   :http:statuscode:`404 Not found`:
     The payment target is unknown.
   :http:statuscode:`502 Bad Gateway`:
     The exchange received an invalid reply from the
     legitimization service.
   :http:statuscode:`504 Gateway Timeout`:
     The exchange did not receive a reply from the legitimization
     service within a reasonable time period.
 
 
 .. http:get:: /kyc-webhook/$PROVIDER_SECTION/*
 .. http:post:: /kyc-webhook/$PROVIDER_SECTION/*
 .. http:get:: /kyc-webhook/$LOGIC/*
 .. http:post:: /kyc-webhook/$LOGIC/*
 
   Alternatively, the KYC confirmation may be triggered by a ``/kyc-webhook``
   request. As KYC **providers** do not necessarily support passing detailed
   information in the URL arguments, the ``/kyc-webhook`` only needs to specify
   either the ``PROVIDER_SECTION`` *or* the ``LOGIC`` (the name of the plugin
   implementing the KYC API).  The API-specific webhook logic must then figure
   out what exactly the webhook is about on its own.  The ``/kyc-webhook/``
   endpoint works for GET or POST, again as details depend on the KYC provider.
   In contrast to ``kyc-proof``, the response does NOT go to the end-users'
   browser and should thus only indicate success or failure.
 
   **Request:**
 
   Details on the request depend on the specific KYC logic that was used.
 
   **Response:**
 
   :http:statuscode:`204 No content`:
     The operation succeeded.
   :http:statuscode:`404 Not found`:
     The specified logic is unknown.
 
 
 .. http:post:: /kyc-wallet
 
   The ``/kyc-wallet`` POST endpoint allows a wallet to notify an exchange if
   it will cross a balance threshold.  Here, the ``balance`` specified should be
   the threshold (from the ``wallet_balance_limit_without_kyc`` array) that the
   wallet would cross, and *not* the *exact* balance of the wallet.  The exchange
   will respond with a wire target UUID. The wallet can then use this UUID to
   being the KYC process at ``/kyc-check/``. The wallet must only proceed to
   obtain funds exceeding the threshold after the KYC process has concluded.
   While wallets could be "hacked" to bypass this measure (we cannot
   cryptographically enforce this), such modifications are a terms of service
   violation which may have legal consequences for the user.
 
   Setup KYC identification for a wallet.  Returns the KYC UUID.  This endpoint
   is used by compliant Taler wallets when they are about to hit the balance
   threshold and thus need to have the customer provide their personal details
   to the exchange.  The wallet is identified by its long-lived reserve public
   key (which is used for P2P payments, not for withdrawals).
 
   **Request:**
 
   The request body must be a `WalletKycRequest` object.
 
   **Response:**
 
   :http:statuscode:`204 No Content`:
     KYC is disabled at this exchange, or the balance is below the
     threshold that requires KYC, or this wallet already satisfied
     the KYC check for the given balance.
   :http:statuscode:`403 Forbidden`:
     The provided signature is invalid.
     This response comes with a standard `ErrorDetail` response.
   :http:statuscode:`451 Unavailable for Legal Reasons`:
     The wallet must undergo a KYC check. A KYC ID was created.
     The response will be a `LegitimizationNeededResponse` object.
 
 .. http:get:: /aml/$OFFICER_PUB/measures
 
   To enable the AML staff SPA to give AML staff a choice of possible measures, a
   new endpoint ``/aml/$OFFICER_PUB/measures`` is added that allows the AML SPA
   to dynamically GET the list of available measures.  It returns a list of known
   KYC checks (by name) with their descriptions and a list of AML programs with
   information about the required context.
 
   **Request:**
 
   *Taler-AML-Officer-Signature*:
     The client must provide Base-32 encoded EdDSA signature with
     ``$OFFICER_PRIV``, affirming the desire to obtain AML data.  Note that
     this is merely a simple authentication mechanism, the details of the
     request are not protected by the signature.
 
   **Response:**
 
   :http:statuscode:`200 Ok`:
     Information about possible measures is returned in a
     `AvailableMeasureSummary` object.
 
 .. http:get:: /aml/$OFFICER_PUB/kyc-statistics/$NAME
 
   Returns the number of KYC events matching the given event type ``$NAME`` in
   the specified time range.  Note that this query can be slow as the
   statistics are computed on-demand. (This is OK as such requests should be
   rare.)
 
   **Request:**
 
   *Taler-AML-Officer-Signature*:
     The client must provide Base-32 encoded EdDSA signature with
     ``$OFFICER_PRIV``, affirming the desire to obtain AML data.  Note that this
     is merely a simple authentication mechanism, the details of the request are
     not protected by the signature.
 
   :query start_date=TIMESTAMP:
     *Optional*. Specifies the date when to
     start looking (inclusive). If not given, the start time of the
     exchange operation is used.
   :query end_date=TIMESTAMP:
     *Optional*. Specifies the date when to
     stop looking (exclusive). If not given, the current date is used.
 
   **Response:**
 
   :http:statuscode:`200 OK`:
     The response will be an `EventCounter` message.
 
 .. http:get:: /aml/$OFFICER_PUB/decisions
 
   **Request:**
 
   *Taler-AML-Officer-Signature*:
     The client must provide Base-32 encoded EdDSA signature with
     ``$OFFICER_PRIV``, affirming the desire to obtain AML data.  Note that
     this is merely a simple authentication mechanism, the details of the
     request are not protected by the signature.
 
   :query limit:
     *Optional*. takes value of the form ``N (-N)``, so that at
     most ``N`` values strictly older (younger) than ``start`` are returned.
     Defaults to ``-20`` to return the last 20 entries (before ``start``).
   :query offset:
     *Optional*. Row number threshold, see ``delta`` for its
     interpretation.  Defaults to ``INT64_MAX``, namely the biggest row id
     possible in the database.
   :query h_payto:
     *Optional*. Account selector. All matching accounts are returned if this
     filter is absent, otherwise only decisions for this account.
   :query active:
     *Optional*. If set to yes, only return active decisions, if no only
     decisions that have been superceeded. Do not give (or use "all") to
     see all decisions regardless of activity status.
   :query investigation:
     *Optional*. If set to yes, only return accounts that are under
     AML investigation, if no only accounts that are not under investigation.
     Do not give (or use "all") to see all accounts regardless of
     investigation status.
 
   **Response:**
 
   :http:statuscode:`200 OK`:
     The response will be an `AmlDecisionsResponse` message.
   :http:statuscode:`204 No content`:
     There are no matching AML records.
   :http:statuscode:`403 Forbidden`:
     The signature is invalid.
   :http:statuscode:`404 Not found`:
     The designated AML account is not known.
   :http:statuscode:`409 Conflict`:
     The designated AML account is not enabled.
 
 .. http:get:: /aml/$OFFICER_PUB/attributes/$H_PAYTO
 
   Obtain attributes obtained as part of AML/KYC processes for a
   given account.
 
   **Request:**
 
   *Taler-AML-Officer-Signature*:
     The client must provide Base-32 encoded EdDSA signature with
     ``$OFFICER_PRIV``, affirming the desire to obtain AML data.  Note that
     this is merely a simple authentication mechanism, the details of the
     request are not protected by the signature.
 
   :query limit:
     *Optional*. takes value of the form ``N (-N)``, so that at
     most ``N`` values strictly older (younger) than ``start`` are returned.
     Defaults to ``-20`` to return the last 20 entries (before ``start``).
   :query offset:
     *Optional*. Row number threshold, see ``delta`` for its
     interpretation.  Defaults to ``INT64_MAX``, namely the biggest row id
     possible in the database.
 
   **Response:**
 
   :http:statuscode:`200 OK`:
     The response will be an `KycAttributes` message.
   :http:statuscode:`204 No content`:
     There are no matching KYC attributes.
   :http:statuscode:`403 Forbidden`:
     The signature is invalid.
   :http:statuscode:`404 Not found`:
     The designated AML account is not known.
   :http:statuscode:`409 Conflict`:
     The designated AML account is not enabled.
 
 .. http:post:: /aml/$OFFICER_PUB/decision
 
   Make an AML decision. Triggers the respective action and
   records the justification.
 
   **Request:**
 
   The request body must be an `AmlDecisionRequest` message.
 
   **Response:**
 
   :http:statuscode:`204 No content`:
     The AML decision has been executed and recorded successfully.
   :http:statuscode:`403 Forbidden`:
     The signature is invalid.
   :http:statuscode:`404 Not found`:
     The address the decision was made upon is unknown to the exchange or
     the designated AML account is not known.
   :http:statuscode:`409 Conflict`:
     The designated AML account is not enabled or a more recent
     decision was already submitted.
 
 Modifications to existing endpoints
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 When withdrawing, the exchange checks if the KYC status is acceptable.  If no
 KYC was done and if either the amount withdrawn over a particular timeframe
 exceeds the threshold or the reserve received received a P2P transfer, then a
 ``451 Unavailable for Legal Reasons`` is returned which redirects the consumer
 to the new ``/kyc-check/`` handler.
 
 When depositing, the exchange aggregator (!) checks the KYC status and if
 negative, returns an additional information field via the
 ``aggregation_transient`` table which is returned via GET ``/deposts/`` to the
 merchant.
 
 When merging into a reserve, the KYC status is checked and again the
 merge fails with ``451 Unavailable for Legal Reasons`` to trigger the
 KYC process.
 
 To allow the wallet to do the KYC check if it is about to exceed a set balance
 threshold, we modify the ``/keys`` response to add an optional array
 ``wallet_balance_limit_without_kyc`` of threshold amounts is returned.
 Whenever the wallet crosses one of these thresholds for the first time, it
 should trigger the KYC process.  If this field is absent, there is no limit.
 If the field is provided, a correct wallet must create a long-term
 account-reserve key pair. This should be the same key that is also used to
 receive wallet-to-wallet payments. Then, *before* a wallet performs an
 operation that would cause it to exceed the balance threshold in terms of
 funds held from a particular exchange, it *should* first request the user to
 complete the KYC process.  For that, the wallet should POST to the new
 ``/kyc-wallet`` endpoint, providing its long-term reserve-account public key
 and a signature requesting permission to exceed the account limit.
 
 
 Configuration of external KYC providers
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 For each KYC provider that could contribute to checks the configuration
 specifies a ``$PROVIDER_SECTION`` for each authentication procedure.  For each
 (enabled) provider, the exchange has a logic plugin which (asynchronously)
 determines the redirect URL for a given wire target. See below for a
 description of the high-level process for different providers.
 
 .. code-block:: ini
 
   [kyc-provider-$PROVIDER_ID]
 
   # Which plugin is responsible for this provider?
   LOGIC = PLUGIN_NAME
 
   # Plus additional logic-specific options, e.g.:
   AUTHORIZATION_TOKEN = superdupersecret
 
   # Other logic-specific internal options (example):
   FORM_ID = business_legi_form
 
 
 Configuration of possible KYC/AML checks
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 The configuration specifies a set of possible KYC checks offered by external
 providers, one per configuration section:
 
 .. code-block:: ini
 
   [kyc-check-$CHECK_NAME]
 
   # Which type of check is this? Also determines
   # the SPA form to show to the user for this check.
   #
   # INFO: wait for staff or contact staff out-of band
   #          (only information shown, no SPA action)
   # FORM: SPA should show an inline (HTML) form
   # LINK: SPA may start external KYC process or upload
   #
   TYPE = INFO|LINK|FORM
 
   # Provider id, present only if type is LINK.
   # Refers to a ``kyc-provider-$PROVIDER_ID`` section.
   PROVIDER_ID = id
 
   # Name of the SPA form, if type is FORM
   # "INFO" and "LINK" are reserved and must not be used.
   # The exchange server and the SPA must agree on a list
   # of supported forms and the resulting attributes.
   #
   # The SPA should include a JSON resource file
   # "forms.json" mapping form names to arrays of
   # attribute names each form provides.
   FORM_NAME = name
 
   # Descriptions to use in the SPA to display the check.
   DESCRIPTION = "Upload your passport picture"
   DESCRIPTION_I18N = "{"en":"Upload scan of your passport"}"
 
   # ';'-separated list of fields that the CONTEXT must
   # provide as inputs to this check. For example,
   # for a FORM of type CHOICE, this might state
   # ``choices: string[];``. The type after the ":"
   # is for now purely for documentation and is
   # not checked. However, it may be shown to AML staff
   # when they configure measures.
   REQUIRES = requirement;
 
   # Description of the outputs provided by the check.
   # Basically, the check's output is expected to
   # provide the following fields as attribute inputs into
   # a subsequent AML program.
   # Only given for type FORM; INFO never has any outputs,
   # and for type LINK we can obtain the same information
   # from the CONVERTER via ``--list-outputs``.
   OUTPUTS = business_name street city country registration
 
   # **original** measure to take if the check fails
   # (for any reason, e.g. provider or form fail to
   # satisfy constraints or provider signals user error)
   # Usually should point to a measure that requests
   # AML staff to investigate.  The fallback measure
   # context always includes the reasons for the
   # failure.
   FALLBACK = MEASURE_NAME
 
 The list of possible FORM names is fixed in the SPA
 for a particular exchange release.
 
 The outcome of *any* check should always be uploaded encrypted into the
 ``kyc_attributes`` table.  It MUST include an ``expiration_time``.
 
 The "check_name" value "skip" is reserved and must not be defined. It can be
 used in measures where the AML program must be run immediately without any
 input.
 
 
 Configuration of legitimization requirement triggers
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 The configuration also specifies a set of legitimization rules including the
 condition and the measure the condition triggers, one condition per
 configuration section:
 
 .. code-block:: ini
 
   [kyc-rule-$RULE_NAME]
 
   # Operation that triggers this rule.
   # Must be one of "WITHDRAW", "DEPOSIT",
   # (p2p) "MERGE", (wallet) "BALANCE",
   # (reserve) "CLOSE", "AGGREGATE",
   # "TRANSACTION" or "REFUND".
   OPERATION_TYPE = WITHDRAW
 
   # Space-separated list of next measures to be performed.
   # The SPA should display *all* of these measures to the user.
   # (They have a choice of either which ones, or in
   # which order they are to be performed.)
   # A special measure name "verboten" is used if the
   # specified threshold may never be crossed
   # (under this set of rules).
   NEXT_MEASURES = SWISSNESS KYB
 
   # "YES" if all NEXT_MEASURES will eventually need
   # to be satisfied, "NO" if the user has a choice between
   # them. Not actually enforced by the exchange, but
   # primarily used to inform the user whether this is
   # an "and" or "or". YES for "and".
   IS_AND_COMBINATOR = YES
 
   # YES if the rule (specifically, operation type,
   # threshold, timeframe) and the general nature of
   # the next measure (verboten or approval required)
   # should be exposed to the client.
   # Defaults to NO if not set.
   EXPOSED = YES
 
   # Threshold amount above which the rule is
   # triggered.  The total must be exceeded in the given
   # timeframe.
   THRESHOLD = KUDOS:100
 
   # Timeframe over which the amount to be compared to
   # the THRESHOLD is calculated.
   # Ignored for WALLET-BALANCE.  Can be 'forever'.
   TIMEFRAME = 30 days
 
   # Set to YES to enable the rule (default is NO)
   ENABLED = NO
 
 
 AML programs
 ^^^^^^^^^^^^
 
 AML programs are helper programs that can:
 
 * Generate a list of *required* context field names
   for the helper (introspection!) using the "--required-context"
   command-line switch. The output should use the same
   syntax as the REQUIRES clause of ``[kyc-check-]``
   configuration sections, except that new lines
   MUST be used to separate fields instead of ";".
 * Generate a list of *required* attribute names
   for the helper (introspection!) using the "--required-attributes"
   command-line switch. The output should use the same
   list of names as the ATTRIBUTES in the
   ``[kyc-provider-]`` configuration section
   (but may also include FORM field names).
 * Process an input JSON object of type
   `AmlProgramInput` into a JSON object of
   type `AmlOutcome`.
   This is the default behavior if no command-line switches
   are provided.
 
 If the AML program fails (exits with a failure code or
 does not provide well-formed JSON output) the AML/KYC
 process continues with the FALLBACK measure. This should
 usually be one that asks AML staff to contact the
 systems administrator.
 
 AML programs are listed in the configuration file, one program per section:
 
 .. code-block:: ini
 
   [aml-program-$PROG_NAME]
 
   # Program to run.
   COMMAND = taler-helper-aml-pep
 
   # Human-readable description of what this
   # AML helper program will do. Used to show
   # to the AML staff.
   DESCRIPTION = "check if the customer is a PEP"
 
   # True if this AML program is enabled (and thus can be
   # used in measures and exposed to AML staff).
   # Optional, default is NO.
   ENABLED = YES
 
   # **original** measure to take if COMMAND fails
   # Usually points to a measure that asks AML staff
   # to contact the systems administrator. The fallback measure
   # context always includes the reasons for the
   # failure.
   FALLBACK = MEASURE_NAME
 
 
 Configuration of measures
 ^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Finally, the configuration specifies a set of
 **original** *measures* one per configuration section:
 
 .. code-block:: ini
 
   [kyc-measure-$MEASURE_NAME]
 
   # Possible check for this measure.  Optional.
   # If not given, PROGRAM should be run immediately
   # (on an empty set of attributes).
   CHECK_NAME = IB_FORM
 
   # Context for the check. The context can be
   # just an empty JSON object if there is none.
   CONTEXT = {"choices":["individual","business"]}
 
   # Program name to run on the context and check data to
   # determine the outcome and next measure.
   # Refers to a ``[aml-program-$PROG_NAME]`` section name.
   PROGRAM = taler-aml-program
 
   # Optional. Set to YES to allow this measure to be
   # done voluntarily by a client. Used to offer the
   # KYC SPA to display measure even if they are
   # not required. Default is NO.
   VOLUNTARY = YES/NO
 
 
 If ``CHECK_NAME`` is set to "SKIP" (or is not provided at all), the AML
 ``PROGRAM`` is to be run immediately.  This is useful if no client-interaction
 is required to arrive at a decision.
 
 .. note::
 
   The list of *measures* is not complete: AML staff may freely define new
   measures dynamically, usually by selecting checks, an AML program, and
   providing context.
 
 
 Sanity checking
 ^^^^^^^^^^^^^^^
 
 On start-up, ``taler-exchange-httpd`` should sanity-check its
 configuration. Specifically, it should validate that for all AML programs the
 input requirements (attributes and context) are claimed to be satisfied by the
 respective checks that may trigger those programs, and similarly that for all
 checks the original measures satisfy the context requirements for their KYC
 checks.
 
 As a result, any component (AML program, form or external check) is warranted
 to be always called with the declared required inputs. Furthermore, we can
 detect if a component fails to produce the required output and the
 configuration contains (presumably safe) FALLBACKs to address this case.  The
 exchange *MUST* detect circular failures, like when a FALLBACK triggers a
 measure that itself immediately triggers again the same FALLBACK.
 
 
 Exchange database schema
 ^^^^^^^^^^^^^^^^^^^^^^^^
 
 We introduce a new ``wire_targets`` table into the exchange database. This
 table is referenced as the source or destination of payments (regular deposits
 and also P2P payments).  A positive side-effect is that we reduce duplication
 in the ``reserves_in``, ``wire_out`` and ``deposits`` tables as they can
 reference this table.
 
 We introduce a new ``legitimization_processes`` table that tracks the status
 of a legitimization process at a provider, including the configuration section
 name, the user/account name at the provider, and some legitimization
 identifier for the process at the provider.  In this table, we additionally
 store information related to the KYC status of the underlying payto://-URI, in
 particular when the KYC expires (0 if it was never done).
 
 Finally, we introduce a new ``legitimization_requirements`` table that
 contains a list of checks required for a particular wire target.  When KYC is
 triggered (say when some endpoint returns an HTTP status code of 451) a
 new requirement is first put into the requirements table. Then, when the
 client identifies as business or individual the specific legitimization
 process is started.  When the taler-exchange-aggregator triggers a KYC check
 the merchant can observe this when a 202 (Accepted) status code is returned
 on GET ``/deposits/`` with the respective legitimization requirement row.
 
 
 .. sourcecode:: sql
 
   CREATE TABLE wire_targets
     (wire_target_serial_id BIGSERIAL UNIQUE
     ,wire_target_h_payto BYTEA PRIMARY KEY CHECK (LENGTH(wire_target_h_payto)=32),
     ,access_token BYTEA UNIQUE CHECK (LENGTH(access_token)=32) DEFAULT gen_random_bytes(32)
     ,target_pub BYTEA CHECK (LENGTH(target_pub)=32) DEFAULT NULL
     ,payto_uri STRING NOT NULL
     )
     PARTITION BY HASH (wire_target_h_payto);
 
   COMMENT ON TABLE wire_targets
     IS 'All recipients of money via the exchange';
   COMMENT ON COLUMN wire_targets.h_payto
     IS 'Unsalted hash of payto_uri';
   COMMENT ON COLUMN wire_targets.access_token
     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)';
   COMMENT ON COLUMN wire_targets.target_pub
     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';
   COMMENT ON COLUMN wire_targets.payto_uri
     IS 'Can be a regular bank account, or also be a URI identifying a reserve-account (for P2P payments)';
 
   CREATE TABLE IF NOT EXISTS legitimization_measures
     (legitimization_measure_serial_id INT8 GENERATED BY DEFAULT AS IDENTITY
     ,access_token BYTEA NOT NULL UNIQUE CHECK (LENGTH(access_token)=32)
      REFERENCES wire_targets (access_token)
     ,start_time INT8 NOT NULL
     ,jmeasures TEXT NOT NULL
     ,display_priority INT4 NOT NULL
     ,is_finished BOOL NOT NULL DEFAULT(FALSE)
     )
     PARTITION BY HASH (access_token);
 
   COMMENT ON TABLE legitimization_measures
     IS 'Rules that have been triggered for the account (FIXME: check this is consistent with usage)';
   COMMENT ON COLUMN legitimization_measures.access_token
     IS 'Used to uniquely identify the account and as a symmetric access control mechanism for the SPA';
   COMMENT ON COLUMN legitimization_measures.start_time
     IS 'Time when the measure was triggered (by decision or rule)';
   COMMENT ON COLUMN legitimization_measures.jmeasures
     IS 'JSON object of type LegitimizationMeasures with KYC/AML measures for the account encoded';
   COMMENT ON COLUMN legitimization_measures.display_priority
     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';
   COMMENT ON COLUMN legitimization_measures.is_finished
     IS 'Set to TRUE if this set of measures was processed; used to avoid indexing measures that are done';
 
   CREATE INDEX ON legitimization_measures (access_token)
     WHERE NOT is_finished;
 
   CREATE TABLE legitimization_outcomes
     (outcome_serial_id INT8 GENERATED BY DEFAULT AS IDENTITY
     ,h_payto BYTEA CHECK (LENGTH(h_payto)=32)
      REFERENCES wire_targets (wire_target_h_payto)
     ,decision_time INT8 NOT NULL DEFAULT(0)
     ,expiration_time INT8 NOT NULL DEFAULT(0)
     ,jproperties TEXT,
     ,new_measure_name TEXT,
     ,to_investigate BOOL NOT NULL
     ,is_active BOOL NOT NULL DEFAULT(TRUE)
     ,jnew_rules TEXT NOT NULL
     )
     PARTITION BY HASH (h_payto);
 
   COMMENT ON TABLE legitimization_outcomes
     IS 'Outcomes can come from AML programs';
   COMMENT ON COLUMN legitimization_outcomes.h_payto
     IS 'hash of the payto://-URI this outcome is about';
   COMMENT ON COLUMN legitimization_outcomes.decision_time
     IS 'when was this outcome decided';
   COMMENT ON COLUMN legitimization_outcomes.expiration_time
     IS 'time when the decision expires and the expiration jnew_rules should be applied';
   COMMENT ON COLUMN legitimization_outcomes.jproperties
     IS 'JSON object of type AccountProperties, such as PEP status, business domain, risk assessment, etc.';
   COMMENT ON COLUMN legitimization_outcomes.to_investigate
     IS 'AML staff should investigate the activity of this account';
   COMMENT ON COLUMN legitimization_outcomes.is_active
     IS 'TRUE if this is the current authoritative legitimization outcome';
   COMMENT ON COLUMN legitimization_outcomes.new_measure_name
     IS 'space-separated list of measures to trigger immediately, NULL for none, prefixed with a "+" to indicate AND combination for the measures';
   COMMENT ON COLUMN legitimization_outcomes.jnew_rules
     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';
 
   CREATE INDEX legitimization_outcomes_active
     ON legitimization_outcomes(h_payto)
     WHERE is_active;
 
   CREATE TABLE legitimization_processes
     (legitimization_process_serial_id BIGSERIAL UNIQUE
     ,h_payto BYTEA NOT NULL CHECK (LENGTH(h_payto)=64)
      REFERENCES wire_targets (wire_target_h_payto)
     ,start_time INT8 NOT NULL
     ,expiration_time INT8 NOT NULL DEFAULT (0)
     ,legitimization_measure_serial_id INT8
      REFERENCES legitimization_measures (legitimization_measure_serial_id)
     ,measure_index INT4
     ,provider_section TEXT NOT NULL
     ,provider_user_id TEXT DEFAULT NULL
     ,provider_legitimization_id TEXT DEFAULT NULL
     ,redirect_url TEXT DEFAULT NULL
     ,finished BOOLEAN DEFAULT (FALSE)
     )
     PARTITION BY HASH (h_payto);
 
   COMMENT ON TABLE legitimization_processes
     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';
   COMMENT ON COLUMN legitimization_processes.h_payto
     IS 'foreign key linking the entry to the wire_targets table, NOT a primary key (multiple KYC setups are possible per wire target)';
   COMMENT ON COLUMN legitimization_processes.start_time
     IS 'when was the legitimization process initiated';
   COMMENT ON COLUMN legitimization_processes.expiration_time
     IS 'when does the process expire (and needs to be manually set up again)';
   COMMENT ON COLUMN legitimization_processes.measure_index
     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';
   COMMENT ON COLUMN legitimization_processes.provider_section
     IS 'Configuration file section with details about this provider';
   COMMENT ON COLUMN legitimization_processes.provider_user_id
     IS 'Identifier for the user at the provider that was used for the legitimization. NULL if provider is unaware.';
   COMMENT ON COLUMN legitimization_processes.provider_legitimization_id
     IS 'Identifier for the specific legitimization process at the provider. NULL if legitimization was not started.';
   COMMENT ON COLUMN legitimization_processes.legitimization_measure_serial_id
     IS 'measure that enabled this setup, NULL if client voluntarily initiated the process';
   COMMENT ON COLUMN legitimization_processes.redirect_url
     IS 'Where the user should be redirected for this external KYC process';
   COMMENT ON COLUMN legitimization_processes.finished
     IS 'set to TRUE when the specific legitimization process is finished';
 
   CREATE TABLE kyc_attributes
     (kyc_attributes_serial_id INT8 GENERATED BY DEFAULT AS IDENTITY
     ,h_payto BYTEA PRIMARY KEY CHECK (LENGTH(h_payto)=32)
      REFERENCES wire_targets (wire_target_h_payto)
     ,legitimization_process_serial_id INT8
      REFERENCES legitimization_processes (legitimization_process_serial_id)
      DEFAULT NULL
     ,collection_time INT8 NOT NULL
     ,expiration_time INT8 NOT NULL
     ,trigger_outcome_serial INT8 NOT NULL
      REFERENCES legitimization_outcomes(outcome_serial_id)
     ,encrypted_attributes BYTEA NOT NULL
     ) PARTITION BY HASH (h_payto);
 
   COMMENT ON COLUMN kyc_attributes.h_payto
     IS 'identifies the account this is about';
   COMMENT ON COLUMN kyc_attributes.legitimization_process_serial_id
     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';
   COMMENT ON COLUMN kyc_attributes.collection_time
     IS 'when were these attributes collected';
   COMMENT ON COLUMN kyc_attributes.expiration_time
     IS 'when are these attributes expected to expire';
   COMMENT ON COLUMN kyc_attributes.trigger_outcome_serial
     IS 'ID of the outcome that was returned by the AML program based on the KYC data collected';
   COMMENT ON COLUMN kyc_attributes.encrypted_attributes
     IS 'encrypted JSON object with the attribute data the check provided';
 
   CREATE TABLE aml_history
     (aml_history_serial_id INT8 GENERATED BY DEFAULT AS IDENTITY
     ,h_payto BYTEA CHECK (LENGTH(h_payto)=32)
      REFERENCES wire_targets (wire_target_h_payto)
     ,outcome_serial_id INT8 NOT NULL
      REFERENCES legitimization_outcomes (outcome_serial_id)
     ,justification TEXT NOT NULL
     ,decider_pub BYTEA CHECK (LENGTH(decider_pub)=32)
     ,decider_sig BYTEA CHECK (LENGTH(decider_sig)=64);
 
   COMMENT ON TABLE aml_history
     IS 'Records decisions by AML staff with the respective signature and free-form justification.';
   COMMENT ON COLUMN aml_history.outcome_serial_id
     IS 'Actual outcome for the account (included in what decider_sig signs over)';
   COMMENT ON COLUMN aml_history.decider_sig
     IS 'Signature key of the staff member affirming the AML decision; of type AML_DECISION';
 
   CREATE TABLE kyc_events
     (kyc_event_serial_id INT8 GENERATED BY DEFAULT AS IDENTITY
     ,event_timestamp INT8 NOT NULL
     ,event_type TEXT NOT NULL);
 
   COMMENT ON TABLE kyc_events
     IS 'Records of key events for statistics. Populated via triggers.';
   COMMENT ON COLUMN kyc_events.event_type
     IS 'Name of the event, such as account-open or sar-filed';
 
   CREATE INDEX kyc_event_index
     ON kyc_events(event_type,event_timestamp);
 
 
 The ``jmeasures`` JSON in the ``legitimization_measures``
 table is of type `LegitimizationMeasures`.
 
 The ``jnew_rules`` JSON in the ``legitimization_outcomes``
 table is of type `LegitimizationRuleSet`.
 
 The ``jproperties`` JSON in the ``legitimization_outcomes`` table is of
 type `AccountProperties`.
 
 
 KYC forms
 ^^^^^^^^^
 
 The KYC SPA run by clients needs to support three TYPEs of checks. INFO is
 only about displaying the provided information, LINK is about setting up an
 exteral KYC check and redirecting there. FORM is about displaying a particular
 (HTML) form to the user and POSTing the entered information directly with the
 exchange.  Here we describe the forms that must be supported:
 
 * **CHOICE**: Asks the client a multiple-choice question.  The context must
   include "choices: string[]" with a list of choices to show.  Used, for
   example, to ask a client if they are an individual or a business.  The
   resulting HTML FORM field name must be "choice" and it must be mapped to
   strings from the choices list.
 
 * **UPLOAD**: Asks the client to upload a single file.
   The context must include a ``validity_duration`` which
   will be converted to the ``expiration_time`` for
   the uploaded data.  The context may furthermore include
   ``extensions?: string[]`` with a list of allowed file extensions the client's
   file must end with (e.g. "png", "pdf", "gif").  In the absence of this
   context, any file may be uploaded.  The context may also include a
   ``size_limit?: Integer`` with the maximum file size in bytes that can be
   uploaded.  The resulting HTTP POST should provide at least two fields, "filename" and
   "filedata".  "filename" must be set to the basename of the original file (to
   the extend that it is available), and "filedata" to the base64-encoding of
   the uploaded data.
 
 As with other SPA checks, the KYC form should also show
 the description of the check.
 
 
 Merchant modifications
 ^^^^^^^^^^^^^^^^^^^^^^
 
 A new setting is required where the merchant backend can be configured for a
 business (default) or individual.
 
 We introduce new ``kyc_ok``, ``aml_decision``, ``kyc_timestamp`` and
 ``exchange_kyc_serial`` fields into a new table ``merchant_kyc`` with primary
 keys ``exchange_url`` and ``account_serial``.  This status is updated whenever
 a deposit is created or tracked, or whenever the mechant backend receives a
 ``/kyc-check/`` response from the exchange.  Initially,
 ``exchange_kyc_serial`` is zero, indicating that the merchant has not yet made
 any deposits and thus does not have an account at the exchange.
 
 A new private endpoint ``/kyc`` is introduced which allows frontends to
 request the ``/kyc`` status of any configured account (including with long
 polling).  If the KYC status is negative or the ``kyc_timestamp`` not recent
 (say older than one month), the merchant backend will re-check the KYC status
 at the exchange (and update its cached status).  The endpoint then returns
 either that the KYC is OK, or information (same as from the exchange endpoint)
 to begin the KYC process.
 
 The merchant backend uses the new field to remember that a KYC is pending
 (after detection in ``taler-merchant-depositcheck``) and the SPA then shows a
 notification whenever the staff is logged in to the system.  The notification
 can be hidden for the current day (remembered in local storage).
 
 The notification links to a (new) KYC status page. When opened, the KYC SPA
 first re-checks the KYC status with the exchange.  If the KYC is still
 unfinished, that SPA will show forms, links or contact information to begin
 the KYC process (for example, redirecting to the OAuth 2.0 login page of the
 legitimization resource server), otherwise it shows that the KYC process is
 done. If the KYC is unfinished, the merchant SPA should use long-polling on
 the KYC status on this page to ensure it is always up-to-date, and change to
 ``KYC satisfied`` should the long-poller return with positive news.
 
   ..note::
 
     Semi-related: The TMH_setup_wire_account() is changed to use
     128-bit salt values (to keep ``deposits`` table small) and checks for salt
     to be well-formed should be added "everywhere".
 
 
 
 Bank requirements
 ^^^^^^^^^^^^^^^^^
 
 The exchange primarily requires a KYC provider to be operated by the
 bank that offers an endpoint for with an API implemented by one of
 the logic plugins (and the respective legitimization configuration).
 
 
 Logic plugins
 ^^^^^^^^^^^^^
 
 The ``$PROVIDER_SECTION`` is based on the name of the configuration section,
 not on the name of the logic plugin (that we call ``$LOGIC``).  Using the
 configuration section, the exchange then determines the logic plugin to use.
 
 This section describes the general API for all of the supported KYC providers,
 as well as some details of how this general API could be implemented by the
 logic for different APIs.
 
 
 General KYC Logic Plugin API
 ----------------------------
 
 This section provides a sketch of the proposed API for the KYC logic plugins.
 
 * initiation of KYC check (``kyc-check``):
 
   - inputs:
     + provider_section (for additional configuration)
     + h_payto
   - outputs:
     + success/provider-failure
     + redirect URL (or NULL)
     + provider_user_id (or NULL)
     + provider_legitimization_id (or NULL)
 
 * KYC status check (``kyc-proof``):
 
   - inputs:
     + provider_section (for additional configuration)
     + h_payto
     + provider_user_id (or NULL)
     + provider_legitimization_id (or NULL)
   - outputs:
     + success/pending/user-aborted/user-failure/provider-failure status code
     + HTML response for end-user
 
 * Webhook notification handler (``kyc-webhook``):
 
   - inputs:
     + HTTP method (GET/POST)
     + rest of URL (after provider_section)
     + HTTP body (if applicable!)
   - outputs:
     + success/pending/user-aborted/user-failure/provider-failure status code
     + h_payto (for DB status update)
     + HTTP response to be returned to KYC provider
 
 The plugins do not directly interact with the database, the caller sets the
 expiration on ``success`` and also updates ``provider_user_id`` and
 ``provider_legitimization_id`` in the tables as required.
 
 
 For the webhook, we need a way to lookup ``h_payto`` by other data, so the
 KYC logic plugin API should be provided a method lookup with:
 
   - inputs:
     + ``provider_section``
     + ``provider_legitimization_id``
   - outputs:
     + ``h_payto``
     + ``legitimization_process_row``
 
 
 OAuth 2.0 specifics
 -------------------
 
 In terms of configuration, the OAuth 2.0 logic requires the respective client
 credentials to be configured apriori to enable access to the legitimization
 service.
 
 For the ``/kyc-check/`` endpoint, the OAuth 2.0 logic may need to create and
 store a nonce to be used during ``/kyc-proof/``, depending on the OAuth
 variant used.  This may require another exchange table.  The OAuth 2.0 process
 must then be set up to end at the new ``/kyc-proof/$PROVIDER_ID/`` endpoint.
 
 This ``/kyc-proof/oauth2/`` endpoint must query the OAuth 2.0 server using the
 ``code`` argument provided as a query parameter. Based on the result, it then
 updates the KYC table of the exchange with the legitimization status and
 returns a human-readable KYC status page.
 
 The ``/kyc-webhook/`` is not applicable.
 
 
 Persona specifics
 -----------------
 
 We would use the hosted flow. Endpoints return a ``request-id``, which we should
 log for diagnosis.
 
 For ``/kyc-check/``:
 
 * Post to ``/api/v1/accounts`` using ``reference-id`` set to our ``h_payto``.
   Returns ``id`` (account_id).
 
 * Create ``/verify`` endpoint using ``template-id`` (from configuration),
   and ``account_id`` (from previous step) and a ``reference-id`` (use
   the ``legitimization_serial_id`` for the new process). Set
   ``redirect-uri`` to ``/kyc-proof/$PROVIDER_ID/``.  However, we cannot
   rely on the user clicking this, so we must also configure a webhook.
   The request returns a '``verification-id``.  That we store under
   the ``provider_legitimization_id`` in the database.
 
 For ``/kyc-proof/``:
 
 * Use the ``/api/v1/verifications`` endpoint to get the verification
   status. Requires the ``verification-id`` from the previous step.
   Results include: created/pending/completed/expired (aborted)/failed.
 
 For ``/kyc-webhook/``:
 
 * The webhook is authenticated using a shared secret, which should
   be in the configuration.  So all we should have to do is parse
   the POSTed body to find the status and the ``verification-id`` to
   lookup ``h_payto`` and return the result.
 
 
 KYC AID specifics
 -----------------
 
 For ``/kyc-check/``:
 
 * Post to ``/applicants`` with a type (person or company) to
   obtain ``applicant_id``. Store that under ``provider_user_id``.
   ISSUE: *we* need to get the company_name, business_activity_id
   and registration_country before this somehow!
 
 * start with create form URL ``/forms/$FORM_ID/urls``
   providing our ``h_payto`` as the ``external_applicant_id``,
   using the ``applicant_id`` from above,
   and the ``/kyc-proof/$PROVIDER_ID`` for the ``redirect_url``.
 
 * redirect customer to the ``form_url``,
   store the ``verification_id`` under ``provider_legitimization_id``
   in the database.
 
 For ``/kyc-proof/``:
 
 * Not needed, just return an error.
 
 For ``/kyc-webhook/``:
 
 * For security, we should probably simply trigger the GET on
   ``/verifications/{verification_id}`` to not trust an unsigned POST
   to tell us anything for sure.  The result is then returned.
 
 
 Types of KYC events
 ^^^^^^^^^^^^^^^^^^^
 
 The ``/aml/$OFFICER_PUB/kyc-statistics`` endpoint exposes statistics for
 various KYC event types.
 
 We will initially support the use of the following types of KYC events in the
 SPA (and have a dialog to show the total number of any of these for any
 specified time range):
 
 * account-open
 * account-closed
 * voluntary-sar
 * mandatory-sar
 * pep-started
 * pep-ended
 * risky-started
 * risky-ended
 * account-frozen
 * account-unfrozen
 
 Based on these, the SPA should also be albe to show active
 statistics (for any given timestamp) on the total number of:
 
 * open accounts
 * frozen accounts
 * high-risk accounts
 * PEPs served
 
 .. note::
 
    This can be done by simply running the queries with
    a start time of zero and subtracting.
 
 
 Alternatives
 ============
 
 We could also store the access token (returned by OAuth 2.0), but that seems
 slightly more dangerous and given the close business relationship is
 unnecessary. Furthermore, not all APIs offer this.
 
 We could extend the KYC logic API to return key attributes about the user
 (such as legal name, phone number, address, etc.) which we could then sign and
 return to the user.  This would be useful in P2P payments to identify the
 origin of an invoice.  However, we might want to be careful to not disclose
 the key attributes via the API by accident.  This could likely be done by
 limiting access to the respective endpoint to messages with a signature by the
 reserve private key (which is the only case where we care to certify things
 anyway).
 
 
 Drawbacks
 =========
 
 
 Discussion / Q&A
 ================
 
 (This should be filled in with results from discussions on mailing lists / personal communication.)
 
 
 If you have questions, remarks or suggestions regarding this information,
 please feel free to leave a comment at our
 `TALER Integration Community Hub <https://ich.taler.net/t/gnu-taler-exchange-documentation/78>`_.