KYC design update

1 files changed, 29 insertions, 65 deletions

diff --git a/design-documents/023-taler-kyc.rst b/design-documents/023-taler-kyc.rst
index 91489fc4..51d0427b 100644
--- a/design-documents/023-taler-kyc.rst
+++ b/design-documents/023-taler-kyc.rst
@@ -59,16 +59,7 @@ ability to initiate a KYC process are not very sensitive).  Given this pair,
 the ``/kyc/`` endpoint returns either the (positive) KYC status or redirects
 the client (302) to the current stage of the KYC process.  The redirection is
 offered using an HTTP-redirect for Web-based clients and a JSON body with
-information for triggering App-based KYC (via intents or opening some new type
-of KYC URI).
-
-A new ``/management/kyc/`` endpoint is introduced that allows exchange
-operators to reset the KYC status (using hash of payto:// as the key) of
-certain account holders. Batch operations should likely be supported (where an
-array of hashes is provided).  The handler should return the number of
-accounts that were actually modified. The idea is that the bank would use this
-to update its KYC records given an updated list of embargoed entities.
-This will also require a new ``taler-exchange-offline`` subcommand.
+information for triggering a browser-based KYC process using OAuth 2.0.
 
 When withdrawing, the exchange checks if the KYC status is acceptable.  If no
 KYC was done and if either the amount withdrawn over the last X days exceeds
@@ -84,15 +75,15 @@ at the new ``/kyc/`` handler.
 When tracking deposits, the exchange also adds the ``wire_target_serial`` to
 the reply if the KYC status is negative.
 
-The aggregator is modified to only create the ``wire_out`` record, but not
-the ``prewire`` record.
+The aggregator is modified to only SELECT deposits where the ``wire_target``
+has the KYC status set to positive (unless KYC is disabled in the exchange
+configuration).
+
 
-A new ``taler-exchange-kyc`` process checks ``wire_out`` records for which the
-``wire_target`` has the KYC status set to positive, and creates ``prewire``
-records (and sets the ``wire_out`` to ``done``.
+  ..note::
 
-We may want to consider directly deleting prewire records instead of setting
-them to ``finished`` in ``taler-exchange-transfer``.
+    Unrelated: We may want to consider directly deleting prewire records
+    instead of setting them to ``finished`` in ``taler-exchange-transfer``.
 
 
 
@@ -101,7 +92,8 @@ Exchange database schema changes
 
 Note that there is may be some slight complication in the migration as the
 h_wire in deposits is salted, while the h_payto in the new wire_targets is
-expected to be unsalted. So converting the existing information to create the wire_targets table will be tricky!
+expected to be unsalted. So converting the existing information to create the
+wire_targets table will be tricky!
 
 We can *either* not support a fully automatic migration, or do an "expensive"
 migration with C logic (so not just SQL statements).
@@ -118,6 +110,7 @@ migration with C logic (so not just SQL statements).
   ,h_payto BYTEA NOT NULL CHECK (LENGTH(h_payto)=64),
   ,payto_uri STRING NOT NULL
   ,kyc_ok BOOLEAN NOT NULL DEFAULT (false)
+  ,oauth_username STRING NOT NULL
   ,PRIMARY KEY (h_wire)
   );
   COMMENT ON TABLE wire_targets
@@ -128,6 +121,8 @@ migration with C logic (so not just SQL statements).
     IS 'Unsalted hash of payto_uri';
   COMMENT ON COLUMN wire_targets.kyc_ok
     IS 'true if the KYC check was passed successfully';
+  COMMENT ON COLUMN wire_targets.oauth_username
+    IS 'Name of the user that was used for OAuth 2.0-based legitimization';
   --
   -- NOTE: logic to fill wire_target missing, so this
   -- CANNOT work if the database contains any data!
@@ -188,71 +183,40 @@ can be hidden for the current day (remembered in local storage).
 
 The notification links to a (new) KYC status page. When opened, the KYC status
 page first re-checks the KYC status with the exchange.  If the KYC is still
-unfinished, that page contains another link to begin/resume the KYC process,
-otherwise it shows that the KYC process is done. If the KYC is unfinished, the
-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.
+unfinished, that page contains another link to begin the KYC process
+(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 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.
 
 
 Bank requirements
 ^^^^^^^^^^^^^^^^^
 
-The exchange primarily requires two endpoints from the bank, one to initiate a
-KYC process, and a second one to check if a KYC process has successfully
-completed.  The latter must also be accessible to the auditor.  Here, the
-exchange (or auditor) would preferably pass either the (1) hash of the
-payto://-URI, (2) the payto://-URI itself, or (3) its ``kyc_serial`` into the
-bank's KYC APIs.  (1) is likely best as it contains the least sensitive
-information in the request and still allows the auditor to make a semantically
-meaningful request to the bank's KYC API; (2) may allow the bank to extract
-the IBAN, which could be helpful in certain cases but might limit the
-introduction of new URI schema and may leak information; (3) is most compact
-in terms of what the bank would have to persist with its KYC data, but would
-theoretically allow the exchange to manipulate indices to not pay out certain
-customers despite them having done KYC without easy detection by the auditor.
-
-If possible, the endpoint to check if a KYC process has finished would
-support long-polling.
-
-If possible, the process that allows the user to perform the KYC would
-allow us to trigger the exchange's ``/kyc/`` endpoint at the end, to
-allow the exchange to immediately learn about the completed process.
-
+The exchange primarily requires an OAuth 2.0 login page where the user
+can either login (and share an access token that grants access to only
+the username) or register to initiate the KYC process.
 
 
 Alternatives
 ============
 
-We could have some (new?) component periodically re-check the KYC status of
-all targets for which the status is currently negative (and for which we have
-pending outgoing transactions). However, this may just put undue burden on the
-bank's KYC API.
+We may not need the oauth_username, but it seems saner to store it to
+provide a link to the legitimization resource server.
 
-The bank's KYC API could return a unique identifier to the exchange whenever
-it initiates a KYC process, and the exchange could store that ID. However,
-this may create issues if multiple KYC processes are initiated for the same
-entity (and this is likely not detectable by the bank at that time). Also,
-this information would again not be reasonably verifiable by the auditor.
+We could also store the access token, but that seems slightly more
+dangerous and given the close business relationship is unnecessary.
 
-The exchange could periodically check the KYC status with the bank instead of
-relying on the proposed explicit management KYC revocation API. This may make
-revocation simpler for the bank, but OTOH may create many additional useless
-API requests to the bank's KYC infrastructure.
+We may want to store some additional "permission level" obtained from the
+resource server to say for which of the operations (see requirements section)
+the legitimization is sufficient.
 
 
 
 Drawbacks
 =========
 
-If the bank fails to trigger the ``/kyc/`` handler of the exchange after
-completion of the KYC process, the exchange will not notice the status change
-until the merchant backend makes the next inquiry (which would usually have to
-be triggered manually by the merchant).
-
-The solution may require changes to the bank's existing KYC implementation to
-store the KYC status under the (hash of the) payto://-URI.
-
 
 Discussion / Q&A
 ================