Add documentation. Add options to enable/disable the hash providers. Add the option for setup barrier for rotation per requests strategy.

docs/MSC2140_MSC2134.md

@@ -17,6 +17,7 @@ NOTE: the v1 is deprecated, therefore recommend to use only v2 and disable v1 (d
 matrix:
   v1: false
 ```
+NOTE: Riot Web version 1.5.5 and below checks the v1 for backward compatibility.
 
 ## Terms
 
@@ -35,13 +36,85 @@ policy:
           url: https://ma1sd.host.tld/term_fr.html  # localized url
       regexp:
         - '/_matrix/identity/v2/account.*'
-        - '/_matrix/identity/v2/hash_lookup'
+        - '/_matrix/identity/v2/hash_details'
+        - '/_matrix/identity/v2/lookup'
 ```
 Where:
 
 - `term_name` -- name of the terms.
-- `regexp` -- regexp patterns for API.
+- `version` -- the terms version.
+- `lang` -- the term language.
+- `name` -- the name of the term.
+- `url` -- the url of the term.
+- `regexp` -- regexp patterns for API which should be available only after accepting the terms.
+
+API will be checks for accepted terms only with authorization.
+There are the next API:
+- [`GET /_matrix/identity/v2/account`](https://matrix.org/docs/spec/identity_service/r0.3.0#get-matrix-identity-v2-account) - Gets information about what user owns the access token used in the request.
+- [`POST /_matrix/identity/v2/account/logout`](https://matrix.org/docs/spec/identity_service/r0.3.0#post-matrix-identity-v2-account-logout) - Logs out the access token, preventing it from being used to authenticate future requests to the server.
+- [`GET /_matrix/identity/v2/hash_details`](https://matrix.org/docs/spec/identity_service/r0.3.0#get-matrix-identity-v2-hash-details) - Gets parameters for hashing identifiers from the server. This can include any of the algorithms defined in this specification.
+- [`POST /_matrix/identity/v2/lookup`](https://matrix.org/docs/spec/identity_service/r0.3.0#post-matrix-identity-v2-lookup) - Looks up the set of Matrix User IDs which have bound the 3PIDs given, if bindings are available. Note that the format of the addresses is defined later in this specification.
+- [`POST /_matrix/identity/v2/validate/email/requestToken`](https://matrix.org/docs/spec/identity_service/r0.3.0#post-matrix-identity-v2-validate-email-requesttoken) - Create a session for validating an email address.
+- [`POST /_matrix/identity/v2/validate/email/submitToken`](https://matrix.org/docs/spec/identity_service/r0.3.0#post-matrix-identity-v2-validate-email-submittoken) - Validate ownership of an email address.
+- [`GET /_matrix/identity/v2/validate/email/submitToken`](https://matrix.org/docs/spec/identity_service/r0.3.0#get-matrix-identity-v2-validate-email-submittoken) - Validate ownership of an email address.
+- [`POST /_matrix/identity/v2/validate/msisdn/requestToken`](https://matrix.org/docs/spec/identity_service/r0.3.0#post-matrix-identity-v2-validate-msisdn-requesttoken) - Create a session for validating a phone number.
+- [`POST /_matrix/identity/v2/validate/msisdn/submitToken`](https://matrix.org/docs/spec/identity_service/r0.3.0#post-matrix-identity-v2-validate-msisdn-submittoken) - Validate ownership of a phone number.
+- [`GET /_matrix/identity/v2/validate/msisdn/submitToken`](https://matrix.org/docs/spec/identity_service/r0.3.0#get-matrix-identity-v2-validate-msisdn-submittoken) - Validate ownership of a phone number.
+- [`GET /_matrix/identity/v2/3pid/getValidated3pid`](https://matrix.org/docs/spec/identity_service/r0.3.0#get-matrix-identity-v2-3pid-getvalidated3pid) - Determines if a given 3pid has been validated by a user.
+- [`POST /_matrix/identity/v2/3pid/bind`](https://matrix.org/docs/spec/identity_service/r0.3.0#post-matrix-identity-v2-3pid-bind) - Publish an association between a session and a Matrix user ID.
+- [`POST /_matrix/identity/v2/3pid/unbind`](https://matrix.org/docs/spec/identity_service/r0.3.0#post-matrix-identity-v2-3pid-unbind) - Remove an association between a session and a Matrix user ID.
+- [`POST /_matrix/identity/v2/store-invite`](https://matrix.org/docs/spec/identity_service/r0.3.0#post-matrix-identity-v2-store-invite) - Store pending invitations to a user's 3pid.
+- [`POST /_matrix/identity/v2/sign-ed25519`](https://matrix.org/docs/spec/identity_service/r0.3.0#post-matrix-identity-v2-sign-ed25519) - Sign invitation details.
+
+There is only one exception: [`POST /_matrix/identity/v2/terms`](https://matrix.org/docs/spec/identity_service/r0.3.0#post-matrix-identity-v2-terms) which uses for accepting the terms and requires the authorization.
+
+## [Hash lookup](https://github.com/matrix-org/matrix-doc/blob/hs/hash-identity/proposals/2134-identity-hash-lookup.md)
+
+```.yaml
+hashing:
+  enabled: true # enable or disable the hash lookup MSC2140 (default to false)
+  pepperLength: 20 # length of the pepper value (default is 20)
+  rotationPolicy: per_requests # or `per_seconds` how often the hashes will be updating
+  hashStorageType: sql # or `in_memory` where the hashes will be stored
+  algorithms:
+    - none   # the same as v1 bulk lookup
+    - sha256 # hash the 3PID and pepper.
+  delay: 10 # how often hashes will be updated if rotation policy = per_seconds (default is 10)
+  requests: 10 # how many lookup requests will be performed before updating hashes if rotation policy = per_requests (default is 10)
+```
+
+When enabled and client requests the `none` algorithms then hash lookups works as v1 bulk lookup.
+
+Sha256 algorithm supports only sql, memory and exec 3PID providers.
+For sql provider (i.e. for the `synapseSql`):
+```.yaml
+synapseSql:
+  lookup:
+    query: 'select user_id as mxid, medium, address from user_threepids' # query for retrive 3PIDs for hashes.
+```
+
+For general sql provider:
+```.yaml
+sql:
+  lookup:
+    query: 'select user as mxid, field1 as medium, field2 as address from some_table' # query for retrive 3PIDs for hashes.
+```
+
+Each query should return the `mxid`, `medium` and `address` fields.
 
 
-## Hash lookup
+For memory providers:
+```.yaml
+memory:
+  hashEnabled: true # enable the hash lookup (defaults is false)
+```
+
+For exec providers:
+```.yaml
+exec:
+  identity:
+    hashEnabled: true # enable the hash lookup (defaults is false)
+```
+
+NOTE: Federation requests work only with `none` algorithms.
 

src/main/java/io/kamax/mxisd/backend/exec/ExecIdentityStore.java

@@ -173,6 +173,10 @@ public class ExecIdentityStore extends ExecStore implements IThreePidProvider {
 
     @Override
     public Iterable<ThreePidMapping> populateHashes() {
+        if (!cfg.isHashLookup()) {
+            return Collections.emptyList();
+        }
+
         Processor<List<ThreePidMapping>> p = new Processor<>();
         p.withConfig(cfg.getLookup().getBulk());
 

src/main/java/io/kamax/mxisd/backend/memory/MemoryIdentityStore.java

@@ -174,6 +174,10 @@ public class MemoryIdentityStore implements AuthenticatorProvider, DirectoryProv
 
     @Override
     public Iterable<ThreePidMapping> populateHashes() {
+        if (!cfg.isHashEnabled()) {
+            return Collections.emptyList();
+        }
+
         return cfg.getIdentities().stream()
             .map(mic -> mic.getThreepids().stream().map(mtp -> new ThreePidMapping(mtp.getMedium(), mtp.getAddress(), mic.getUsername())))
             .flatMap(s -> s).collect(

src/main/java/io/kamax/mxisd/config/ExecConfig.java

@@ -309,6 +309,7 @@ public class ExecConfig {
         private Boolean enabled;
         private int priority;
         private Lookup lookup = new Lookup();
+        private boolean hashLookup = false;
 
         public Boolean isEnabled() {
             return enabled;
@@ -334,6 +335,13 @@ public class ExecConfig {
             this.lookup = lookup;
         }
 
+        public boolean isHashLookup() {
+            return hashLookup;
+        }
+
+        public void setHashLookup(boolean hashLookup) {
+            this.hashLookup = hashLookup;
+        }
     }
 
     public static class Profile {

src/main/java/io/kamax/mxisd/config/HashingConfig.java

@@ -15,6 +15,7 @@ public class HashingConfig {
     private RotationPolicyEnum rotationPolicy;
     private HashStorageEnum hashStorageType;
     private long delay = 10;
+    private int requests = 10;
     private List<Algorithm> algorithms = new ArrayList<>();
 
     public void build() {
@@ -26,6 +27,9 @@ public class HashingConfig {
             if (RotationPolicyEnum.per_seconds == rotationPolicy) {
                 LOGGER.info("   Rotation delay: {}", delay);
             }
+            if (RotationPolicyEnum.per_requests == rotationPolicy) {
+                LOGGER.info("   Rotation after requests: {}", requests);
+            }
             LOGGER.info("   Algorithms: {}", algorithms);
         } else {
             LOGGER.info("Hash configuration disabled, used only `none` pepper.");
@@ -87,6 +91,14 @@ public class HashingConfig {
         this.delay = delay;
     }
 
+    public int getRequests() {
+        return requests;
+    }
+
+    public void setRequests(int requests) {
+        this.requests = requests;
+    }
+
     public List<Algorithm> getAlgorithms() {
         return algorithms;
     }

src/main/java/io/kamax/mxisd/config/memory/MemoryStoreConfig.java

@@ -27,6 +27,7 @@ public class MemoryStoreConfig {
 
     private boolean enabled;
     private List<MemoryIdentityConfig> identities = new ArrayList<>();
+    private boolean hashEnabled = false;
 
     public boolean isEnabled() {
         return enabled;
@@ -44,6 +45,14 @@ public class MemoryStoreConfig {
         this.identities = identities;
     }
 
+    public boolean isHashEnabled() {
+        return hashEnabled;
+    }
+
+    public void setHashEnabled(boolean hashEnabled) {
+        this.hashEnabled = hashEnabled;
+    }
+
     public void build() {
         // no-op
     }

src/main/java/io/kamax/mxisd/hash/HashManager.java

@@ -58,7 +58,7 @@ public class HashManager {
         if (config.isEnabled()) {
             switch (config.getRotationPolicy()) {
                 case per_requests:
-                    this.rotationStrategy = new RotationPerRequests();
+                    this.rotationStrategy = new RotationPerRequests(config.getRequests());
                     break;
                 case per_seconds:
                     this.rotationStrategy = new TimeBasedRotation(config.getDelay());

src/main/java/io/kamax/mxisd/hash/rotation/RotationPerRequests.java

@@ -8,6 +8,11 @@ public class RotationPerRequests implements HashRotationStrategy {
 
     private HashEngine hashEngine;
     private final AtomicInteger counter = new AtomicInteger(0);
+    private final int barrier;
+
+    public RotationPerRequests(int barrier) {
+        this.barrier = barrier;
+    }
 
     @Override
     public void register(HashEngine hashEngine) {
@@ -23,7 +28,7 @@ public class RotationPerRequests implements HashRotationStrategy {
     @Override
     public synchronized void newRequest() {
         int newValue = counter.incrementAndGet();
-        if (newValue >= 10) {
+        if (newValue >= barrier) {
             counter.set(0);
             trigger();
         }