1 files changed, 183 insertions, 0 deletions
diff --git a/taler-exchange-manual.rst b/taler-exchange-manual.rst
index 91865f24..42ec9861 100644
--- a/taler-exchange-manual.rst
+++ b/taler-exchange-manual.rst
@@ -1023,6 +1023,20 @@ Taler KYC Terminology
   *cost*. Interaction with a provider is performed by provider-specific
   *logic*.
 
+Configuration of possible KYC/AML checks
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The configuration specifies a set of possible KYC checks offered by external
+providers.  The names of the configuration sections must being with
+``kyc-check-`` followed by an arbitrary ``$CHECK_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``.
+
+
 
 KYC Configuration Options
 -------------------------
@@ -1724,6 +1738,155 @@ from ``https://git.taler.net/wallet-core.git/``, compile and copy the file
 from the ``dist/prod``.
 
 
+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.
+
+.. ts:def:: AmlProgramInput
+
+  interface AmlProgramInput {
+
+    // JSON object that was provided as
+    // part of the *measure*.  This JSON object is
+    // provided under "context" in the main JSON object
+    // input to the AML program.  This "context" should
+    // satify both the REQUIRES clause of the respective
+    // check and the output of "--requires" from the
+    // AML program's command-line option.
+    context?: Object;
+
+    // JSON object that captures the
+    // output of a ``[kyc-provider-]`` or (HTML) FORM.
+    // The keys in the JSON object will be the attribute
+    // names and the values must be strings representing
+    // the data. In the case of file uploads, the data
+    // MUST be base64-encoded.
+    attributes: Object;
+
+    // JSON array with the results of historic
+    // AML desisions about the account.
+    aml_history: AmlDecisionDetail[];
+
+    // JSON array with the results of historic
+    // KYC data about the account.
+    kyc_history: KycDetail[];
+
+  }
+
+.. ts:def:: AmlOutcome
+
+  interface AmlOutcome {
+
+    // Should the client's account be investigated
+    // by AML staff?
+    // Defaults to false.
+    to_investigate?: boolean;
+
+    // Free-form properties about the account.
+    // Can be used to store properties such as PEP,
+    // risk category, type of business, hits on
+    // sanctions lists, etc.
+    properties?: AccountProperties;
+
+    // Types of events to add to the KYC events table.
+    // (for statistics).
+    events?: string[];
+
+    // KYC rules to apply.  Note that this
+    // overrides *all* of the default rules
+    // until the ``expiration_time`` and specifies
+    // the successor measure to apply after the
+    // expiration time.
+    new_rules: LegitimizationRuleSet;
+
+  }
+
+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
+
+AML Measures
+------------
+
+The exchange 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 to run on the context and check data to
+  # determine the outcome and next measure.
+  PROGRAM = taler-aml-program
+
+If no ``CHECK_NAME`` is 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.
+
+
+
 Setup Linting
 =============
 
@@ -1902,6 +2065,26 @@ The database scheme used by the exchange looks as follows:
 
 .. image:: images/exchange-db.png
 
+The ``jmeasures`` JSON in the ``legitimization_measures``
+table is of type `LegitimizationMeasures`:
+
+.. ts:def:: LegitimizationMeasures
+
+  interface LegitimizationMeasures {
+
+    // Array of legitimization measures that
+    // are to be applied.
+    measures: MeasureInformation[];
+
+    // True if the client is expected to eventually satisfy all requirements.
+    // Default (if missing) is false.
+    is_and_combinator?: boolean;
+
+    // True if the requested operation is categorically forbidden.
+    // The measures array will be empty in this case.
+    verboten: boolean;
+  }
+
 
 .. _Database-upgrades: