work on endpoint spec for AML officers

1 files changed, 52 insertions, 69 deletions

diff --git a/design-documents/023-taler-kyc.rst b/design-documents/023-taler-kyc.rst
index f0907f99..63e879f0 100644
--- a/design-documents/023-taler-kyc.rst
+++ b/design-documents/023-taler-kyc.rst
@@ -1087,10 +1087,7 @@ New endpoints
       counter: Integer;
     }
 
-.. http:get:: /aml/$OFFICER_PUB/decisions/$STATE
-
-  Obtain list of AML decisions (filtered by $STATE).  ``$STATE`` must be
-  either ``normal``, ``pending`` or ``frozen``.
+.. http:get:: /aml/$OFFICER_PUB/decisions
 
   **Request:**
 
@@ -1108,11 +1105,23 @@ New endpoints
     *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 responds will be an `AmlRecords` message.
+    The responds will be an `AmlDecisions` message.
   :http:statuscode:`204 No content`:
     There are no matching AML records.
   :http:statuscode:`403 Forbidden`:
@@ -1124,12 +1133,12 @@ New endpoints
 
   **Details:**
 
-  .. ts:def:: AmlRecords
+  .. ts:def:: AmlDecisions
 
-    interface AmlRecords {
+    interface AmlDecisions {
 
-      // Array of AML records matching the query.
-      records: AmlRecord[];
+      // Array of AML decisions matching the query.
+      records: AmlDecisions[];
     }
 
   .. ts:def:: AmlRecord
@@ -1140,40 +1149,38 @@ New endpoints
       // Identifies a GNU Taler wallet or an affected bank account.
       h_payto: PaytoHash;
 
-      // What is the current AML state.
-      current_state: Integer;
-
-      // Monthly transaction threshold before a review will be triggered
-      threshold: Amount;
-
       // Row ID of the record.  Used to filter by offset.
       rowid: Integer;
 
+      // FIXME: more fields here!
     }
 
 
-.. http:get:: /aml/$OFFICER_PUB/decision/$H_PAYTO
-
-  Obtain deails about an AML decision.
+.. http:get:: /aml/$OFFICER_PUB/attributes/$H_PAYTO
 
   **Request:**
 
   *Taler-AML-Officer-Signature*:
-    The client must provide a Base-32 encoded EdDSA signature with
+    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 history:
-    *Optional*. If set to yes, we return all historic
-    decisions for the account, and not only the last one.
+  :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 responds will be an `AmlDecisionDetails` message.
+    The responds will be an `KycAttributes` message.
   :http:statuscode:`204 No content`:
-    There are no matching AML records for the given payto://-URI.
+    There are no matching KYC attributes.
   :http:statuscode:`403 Forbidden`:
     The signature is invalid.
   :http:statuscode:`404 Not found`:
@@ -1181,48 +1188,27 @@ New endpoints
   :http:statuscode:`409 Conflict`:
     The designated AML account is not enabled.
 
-  **Details:**
-
-  .. ts:def:: AmlDecisionDetails
+  .. ts:def:: KycAttributes
 
-    interface AmlDecisionDetails {
+    interface KycAttributes {
 
-      // Array of AML decisions made for this account. Possibly
-      // contains only the most recent decision if "history" was
-      // not set to 'true'.
-      aml_history: AmlDecisionDetail[];
-
-      // Array of KYC attributes and outcomes obtained for this
-      // account.
-      kyc_attributes: KycDetail[];
-    }
-
-  .. ts:def:: AmlDecisionDetail
-
-    interface AmlDecisionDetail {
-
-      // What was the justification given?
-      justification: string;
-
-      // Outcome of the AML investigation.
-      // Primarily defines new KYC rules to apply.
-      outcome: AmlOutcome;
-
-      // When was this decision made?
-      decision_time: Timestamp;
-
-      // Who made the decision?
-      decider_pub: AmlOfficerPublicKeyP;
+      // Matching KYC attribute history of the account.
+      details: KycDetail[];
 
     }
 
   .. ts:def:: KycDetail
 
+    // FIXME: bad name?
     interface KycDetail {
 
+      // Row ID of the record.  Used to filter by offset.
+      rowid: Integer;
+
       // Name of the configuration section that specifies the provider
-      // which was used to collect the KYC details
-      provider_section: string;
+      // which was used to collect the attributes. NULL if they were
+      // just uploaded via a form by the account owner.
+      provider_section?: string;
 
       // The collected KYC data.  NULL if the attribute data could not
       // be decrypted (internal error of the exchange, likely the
@@ -1232,9 +1218,6 @@ New endpoints
       // Time when the KYC data was collected
       collection_time: Timestamp;
 
-      // Outcome of the AML program.
-      outcome: AmlOutcome;
-
     }
 
 
@@ -1754,7 +1737,7 @@ on GET ``/deposits/`` with the respective legitimization requirement row.
     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 BIGINT GENERATED BY DEFAULT AS IDENTITY
+    (legitimization_measure_serial_id INT8 GENERATED BY DEFAULT AS IDENTITY
     ,target_token BYTEA NOT NULL UNIQUE CHECK (LENGTH(target_token)=32)
      REFERENCES wire_targets (target_token)
     ,start_time INT8 NOT NULL
@@ -1779,7 +1762,7 @@ on GET ``/deposits/`` with the respective legitimization requirement row.
     WHERE NOT is_finished;
 
   CREATE TABLE legitimization_outcomes
-    (outcome_serial_id BIGINT GENERATED BY DEFAULT AS IDENTITY
+    (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)
@@ -1818,12 +1801,12 @@ on GET ``/deposits/`` with the respective legitimization requirement row.
      REFERENCES wire_targets (wire_target_h_payto)
     ,start_time INT8 NOT NULL
     ,expiration_time INT8 NOT NULL DEFAULT (0)
-    ,legitimization_measure_serial_id BIGINT
+    ,legitimization_measure_serial_id INT8
      REFERENCES legitimization_measures (legitimization_measure_serial_id)
     ,measure_index INT4
-    ,provider_section VARCHAR NOT NULL
-    ,provider_user_id VARCHAR DEFAULT NULL
-    ,provider_legitimization_id VARCHAR DEFAULT NULL
+    ,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)
     )
@@ -1853,7 +1836,7 @@ on GET ``/deposits/`` with the respective legitimization requirement row.
     IS 'set to TRUE when the specific legitimization process is finished';
 
   CREATE TABLE kyc_attributes
-    (kyc_attributes_serial_id BIGINT GENERATED BY DEFAULT AS IDENTITY
+    (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
@@ -1880,9 +1863,9 @@ on GET ``/deposits/`` with the respective legitimization requirement row.
     IS 'encrypted JSON object with the attribute data the check provided';
 
   CREATE TABLE aml_history
-    (aml_history_serial_id BIGINT GENERATED BY DEFAULT AS IDENTITY
+    (aml_history_serial_id INT8 GENERATED BY DEFAULT AS IDENTITY
     ,h_payto BYTEA CHECK (LENGTH(h_payto)=32)
-     REFERENCES wire_targets (h_payto)
+     REFERENCES wire_targets (wire_target_h_payto)
     ,outcome_serial_id INT8 NOT NULL
      REFERENCES legitimization_outcomes (outcome_serial_id)
     ,justification TEXT NOT NULL
@@ -1897,7 +1880,7 @@ on GET ``/deposits/`` with the respective legitimization requirement row.
     IS 'Signature key of the staff member affirming the AML decision; of type AML_DECISION';
 
   CREATE TABLE kyc_events
-    (kyc_event_serial_id BIGINT GENERATED BY DEFAULT AS IDENTITY
+    (kyc_event_serial_id INT8 GENERATED BY DEFAULT AS IDENTITY
     ,event_timestamp INT8 NOT NULL
     ,event_type TEXT NOT NULL);