feat: Implement TOTP inmemory classes

CHANGELOG.md

@@ -7,6 +7,22 @@ to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [unreleased]
 
+- Add TOTP recipe
+
+### Database changes:
+- Add new tables for TOTP recipe:
+  - `totp_users` that stores the users that have enabled TOTP
+  - `totp_user_devices` that stores devices (each device has its own secret) for each user
+  - `totp_used_codes` that stores used codes for each user. This is to implement rate limiting and prevent replay attacks.
+
+### New APIs:
+- `POST /recipe/totp/device` to create a new device as well as the user if it doesn't exist.
+- `POST /recipe/totp/device/verify` to verify a device. This is to ensure that the user has access to the device.
+- `POST /recipe/totp/verify` to verify a code and continue the login flow.
+- `PUT /recipe/totp/device` to update the name of a device. Name is just a string that the user can set to identify the device.
+- `GET /recipe/totp/device/list` to get all devices for a user.
+- `POST /recipe/totp/device/remove` to remove a device. If the user has no more devices, the user is also removed.
+
 ## [4.4.2] - 2023-03-16
 
 - Adds null check in email normalisation to fix: https://github.com/supertokens/supertokens-node/issues/514

build.gradle

@@ -65,6 +65,12 @@ dependencies {
     // https://mvnrepository.com/artifact/com.lambdaworks/scrypt
     implementation group: 'com.lambdaworks', name: 'scrypt', version: '1.4.0'
 
+    // https://mvnrepository.com/artifact/com.eatthepath/java-otp
+    implementation group: 'com.eatthepath', name: 'java-otp', version: '0.4.0'
+
+    // https://mvnrepository.com/artifact/commons-codec/commons-codec
+    implementation group: 'commons-codec', name: 'commons-codec', version: '1.15'
+
     compileOnly project(":supertokens-plugin-interface")
     testImplementation project(":supertokens-plugin-interface")
 
@@ -159,4 +165,3 @@ tasks.withType(Test) {
         }
     }
 }
-

config.yaml

@@ -54,6 +54,11 @@ core_config_version: 0
 # (OPTIONAL | Default: 900000) long value. Time in milliseconds for how long a passwordless code is valid for.
 # passwordless_code_lifetime:
 
+# (OPTIONAL | Default: 5) integer value. The maximum number of invalid TOTP attempts that will trigger rate limiting.
+# totp_max_attempts:
+
+# (OPTIONAL | Default: 900) integer value. The time in seconds for which the user will be rate limited once totp_max_attempts is crossed.
+# totp_rate_limit_cooldown_sec:
 
 # (OPTIONAL | Default: installation directory/logs/info.log) string value. Give the path to a file (on your local
 #  system) in which the SuperTokens service can write INFO logs to. Set it to "null" if you want it to log to
@@ -120,4 +125,4 @@ core_config_version: 0
 
 # (OPTIONAL | Default: null). Regex for denying requests from IP addresses that match with the value. Comment this
 # value to deny no IP address.
-# ip_deny_regex:
+# ip_deny_regex:

devConfig.yaml

@@ -54,6 +54,11 @@ core_config_version: 0
 # (OPTIONAL | Default: 900000) long value. Time in milliseconds for how long a passwordless code is valid for.
 # passwordless_code_lifetime:
 
+# (OPTIONAL | Default: 5) integer value. The maximum number of invalid TOTP attempts that will trigger rate limiting.
+# totp_max_attempts:
+
+# (OPTIONAL | Default: 900) integer value. The time in seconds for which the user will be rate limited once totp_max_attempts is crossed.
+# totp_rate_limit_cooldown_sec:
 
 # (OPTIONAL | Default: installation directory/logs/info.log) string value. Give the path to a file (on your local
 #  system) in which the SuperTokens service can write INFO logs to. Set it to "null" if you want it to log to
@@ -120,4 +125,4 @@ disable_telemetry: true
 
 # (OPTIONAL | Default: null). Regex for denying requests from IP addresses that match with the value. Comment this
 # value to deny no IP address.
-# ip_deny_regex:
+# ip_deny_regex:

ee/src/main/java/io/supertokens/ee/EEFeatureFlag.java

@@ -6,10 +6,8 @@
 import com.auth0.jwt.exceptions.JWTVerificationException;
 import com.auth0.jwt.interfaces.DecodedJWT;
 import com.auth0.jwt.interfaces.RSAKeyProvider;
-import com.google.gson.JsonArray;
-import com.google.gson.JsonObject;
-import com.google.gson.JsonParser;
-import com.google.gson.JsonPrimitive;
+import com.google.gson.*;
+import io.supertokens.ActiveUsers;
 import io.supertokens.Main;
 import io.supertokens.ProcessState;
 import io.supertokens.cronjobs.Cronjobs;
@@ -21,6 +19,7 @@
 import io.supertokens.httpRequest.HttpRequest;
 import io.supertokens.httpRequest.HttpResponseException;
 import io.supertokens.output.Logging;
+import io.supertokens.pluginInterface.ActiveUsersStorage;
 import io.supertokens.pluginInterface.KeyValueInfo;
 import io.supertokens.pluginInterface.Storage;
 import io.supertokens.pluginInterface.exceptions.StorageQueryException;
@@ -144,15 +143,50 @@ public Boolean getIsLicenseKeyPresent() {
 
     @Override
     public JsonObject getPaidFeatureStats() throws StorageQueryException {
-        JsonObject result = new JsonObject();
+        JsonObject usageStats = new JsonObject();
         EE_FEATURES[] features = getEnabledEEFeaturesFromDbOrCache();
-        if (Arrays.stream(features).anyMatch(t -> t == EE_FEATURES.DASHBOARD_LOGIN)) {
-            JsonObject stats = new JsonObject();
-            int userCount = StorageLayer.getDashboardStorage(main).getAllDashboardUsers().length;
-            stats.addProperty("user_count", userCount);
-            result.add(EE_FEATURES.DASHBOARD_LOGIN.toString(), stats);
+        ActiveUsersStorage activeUsersStorage = StorageLayer.getActiveUsersStorage(main);
+
+        for (EE_FEATURES feature : features) {
+            if (feature == EE_FEATURES.DASHBOARD_LOGIN) {
+                JsonObject stats = new JsonObject();
+                int userCount = StorageLayer.getDashboardStorage(main).getAllDashboardUsers().length;
+                stats.addProperty("user_count", userCount);
+                usageStats.add(EE_FEATURES.DASHBOARD_LOGIN.toString(), stats);
+            }
+            if (feature == EE_FEATURES.TOTP) {
+                JsonObject totpStats = new JsonObject();
+                JsonArray totpMauArr = new JsonArray();
+
+                for (int i = 0; i < 30; i++) {
+                    long now = System.currentTimeMillis();
+                    long today = now - (now % (24 * 60 * 60 * 1000L));
+                    long timestamp = today - (i * 24 * 60 * 60 * 1000L);
+
+                    int totpMau = activeUsersStorage.countUsersEnabledTotpAndActiveSince(timestamp);
+                    totpMauArr.add(new JsonPrimitive(totpMau));
+                }
+
+                totpStats.add("maus", totpMauArr);
+
+                int totpTotalUsers = activeUsersStorage.countUsersEnabledTotp();
+                totpStats.addProperty("total_users", totpTotalUsers);
+                usageStats.add(EE_FEATURES.TOTP.toString(), totpStats);
+            }
+        }
+
+        JsonArray mauArr = new JsonArray();
+        for (int i = 0; i < 30; i++) {
+            long now = System.currentTimeMillis();
+            long today = now - (now % (24 * 60 * 60 * 1000L));
+            long timestamp = today - (i * 24 * 60 * 60 * 1000L);
+
+            int mau = activeUsersStorage.countUsersActiveSince(timestamp);
+            mauArr.add(new JsonPrimitive(mau));
         }
-        return result;
+
+        usageStats.add("maus", mauArr);
+        return usageStats;
     }
 
     private EE_FEATURES[] verifyLicenseKey(String licenseKey)

implementationDependencies.json

@@ -100,6 +100,16 @@
       "jar": "https://repo1.maven.org/maven2/com/lambdaworks/scrypt/1.4.0/scrypt-1.4.0.jar",
       "name": "Scrypt 1.4.0",
       "src": "https://repo1.maven.org/maven2/com/lambdaworks/scrypt/1.4.0/scrypt-1.4.0-sources.jar"
+    },
+    {
+      "jar": "https://repo1.maven.org/maven2/com/eatthepath/java-otp/0.4.0/java-otp-0.4.0.jar",
+      "name": "Java OTP 0.4.0",
+      "src": "https://repo1.maven.org/maven2/com/eatthepath/java-otp/0.4.0/java-otp-0.4.0-sources.jar"
+    },
+    {
+      "jar": "https://repo1.maven.org/maven2/commons-codec/commons-codec/1.15/commons-codec-1.15.jar",
+      "name": "Commons Codec 1.15",
+      "src": "https://repo1.maven.org/maven2/commons-codec/commons-codec/1.15/commons-codec-1.15-sources.jar"
     }
   ]
 }

src/main/java/io/supertokens/ActiveUsers.java

@@ -0,0 +1,18 @@
+package io.supertokens;
+
+import io.supertokens.pluginInterface.exceptions.StorageQueryException;
+import io.supertokens.storageLayer.StorageLayer;
+
+public class ActiveUsers {
+
+    public static void updateLastActive(Main main, String userId) {
+        try {
+            StorageLayer.getActiveUsersStorage(main).updateLastActive(userId);
+        } catch (StorageQueryException ignored) {
+        }
+    }
+
+    public static int countUsersActiveSince(Main main, long time) throws StorageQueryException {
+        return StorageLayer.getActiveUsersStorage(main).countUsersActiveSince(time);
+    }
+}

src/main/java/io/supertokens/Main.java

@@ -26,6 +26,7 @@
 import io.supertokens.cronjobs.deleteExpiredPasswordResetTokens.DeleteExpiredPasswordResetTokens;
 import io.supertokens.cronjobs.deleteExpiredPasswordlessDevices.DeleteExpiredPasswordlessDevices;
 import io.supertokens.cronjobs.deleteExpiredSessions.DeleteExpiredSessions;
+import io.supertokens.cronjobs.deleteExpiredTotpTokens.DeleteExpiredTotpTokens;
 import io.supertokens.cronjobs.telemetry.Telemetry;
 import io.supertokens.emailpassword.PasswordHashing;
 import io.supertokens.exceptions.QuitProgramException;
@@ -205,6 +206,9 @@ private void init() throws IOException {
         // removes passwordless devices with only expired codes
         Cronjobs.addCronjob(this, DeleteExpiredPasswordlessDevices.getInstance(this));
 
+        // removes expired TOTP used tokens
+        Cronjobs.addCronjob(this, DeleteExpiredTotpTokens.getInstance(this));
+
         // removes expired dashboard session
         Cronjobs.addCronjob(this, DeleteExpiredDashboardSessions.getInstance(this));
 

src/main/java/io/supertokens/authRecipe/AuthRecipe.java

@@ -20,6 +20,8 @@
 import io.supertokens.pluginInterface.RECIPE_ID;
 import io.supertokens.pluginInterface.authRecipe.AuthRecipeUserInfo;
 import io.supertokens.pluginInterface.exceptions.StorageQueryException;
+import io.supertokens.pluginInterface.exceptions.StorageTransactionLogicException;
+import io.supertokens.pluginInterface.totp.sqlStorage.TOTPSQLStorage;
 import io.supertokens.pluginInterface.useridmapping.UserIdMapping;
 import io.supertokens.storageLayer.StorageLayer;
 import io.supertokens.useridmapping.UserIdType;
@@ -59,22 +61,30 @@ public static UserPaginationContainer getUsers(Main main, Integer limit, String
         return new UserPaginationContainer(resultUsers, nextPaginationToken);
     }
 
-    public static void deleteUser(Main main, String userId) throws StorageQueryException {
-        // We clean up the user last so that if anything before that throws an error, then that will throw a 500 to the
-        // developer. In this case, they expect that the user has not been deleted (which will be true). This is as
-        // opposed to deleting the user first, in which case if something later throws an error, then the user has
+    public static void deleteUser(Main main, String userId)
+            throws StorageQueryException, StorageTransactionLogicException {
+        // We clean up the user last so that if anything before that throws an error,
+        // then that will throw a 500 to the
+        // developer. In this case, they expect that the user has not been deleted
+        // (which will be true). This is as
+        // opposed to deleting the user first, in which case if something later throws
+        // an error, then the user has
         // actually been deleted already (which is not expected by the dev)
 
-        // For things created after the intial cleanup and before finishing the operation:
+        // For things created after the intial cleanup and before finishing the
+        // operation:
         // - session: the session will expire anyway
-        // - email verification: email verification tokens can be created for any userId anyway
+        // - email verification: email verification tokens can be created for any userId
+        // anyway
 
-        // If userId mapping exists then delete entries with superTokensUserId from auth related tables and
+        // If userId mapping exists then delete entries with superTokensUserId from auth
+        // related tables and
         // externalUserid from non-auth tables
         UserIdMapping userIdMapping = io.supertokens.useridmapping.UserIdMapping.getUserIdMapping(main, userId,
                 UserIdType.ANY);
         if (userIdMapping != null) {
-            // We check if the mapped externalId is another SuperTokens UserId, this could come up when migrating
+            // We check if the mapped externalId is another SuperTokens UserId, this could
+            // come up when migrating
             // recipes.
             // in reference to
             // https://docs.google.com/spreadsheets/d/17hYV32B0aDCeLnSxbZhfRN2Y9b0LC2xUF44vV88RNAA/edit?usp=sharing
@@ -97,12 +107,20 @@ public static void deleteUser(Main main, String userId) throws StorageQueryExcep
 
     }
 
-    private static void deleteNonAuthRecipeUser(Main main, String userId) throws StorageQueryException {
+    private static void deleteNonAuthRecipeUser(Main main, String userId)
+            throws StorageQueryException, StorageTransactionLogicException {
         // non auth recipe deletion
         StorageLayer.getUserMetadataStorage(main).deleteUserMetadata(userId);
         StorageLayer.getSessionStorage(main).deleteSessionsOfUser(userId);
         StorageLayer.getEmailVerificationStorage(main).deleteEmailVerificationUserInfo(userId);
         StorageLayer.getUserRolesStorage(main).deleteAllRolesForUser(userId);
+
+        TOTPSQLStorage storage = StorageLayer.getTOTPStorage(main);
+        storage.startTransaction(con -> {
+            storage.removeUser_Transaction(con, userId);
+            storage.commitTransaction(con);
+            return null;
+        });
     }
 
     private static void deleteAuthRecipeUser(Main main, String userId) throws StorageQueryException {

src/main/java/io/supertokens/config/CoreConfig.java

@@ -56,6 +56,12 @@ public class CoreConfig {
     @JsonProperty
     private long passwordless_code_lifetime = 900000; // in MS
 
+    @JsonProperty
+    private int totp_max_attempts = 5;
+
+    @JsonProperty
+    private int totp_rate_limit_cooldown_sec = 900; // in seconds (Default 15 mins)
+
     private final String logDefault = "asdkfahbdfk3kjHS";
     @JsonProperty
     private String info_log_path = logDefault;
@@ -106,10 +112,13 @@ public class CoreConfig {
     private int bcrypt_log_rounds = 11;
 
     // TODO: add https in later version
-//	# (OPTIONAL) boolean value (true or false). Set to true if you want to enable https requests to SuperTokens.
-//	# If you are not running SuperTokens within a closed network along with your API process, for 
-//	# example if you are using multiple cloud vendors, then it is recommended to set this to true.
-//	# webserver_https_enabled:
+    // # (OPTIONAL) boolean value (true or false). Set to true if you want to enable
+    // https requests to SuperTokens.
+    // # If you are not running SuperTokens within a closed network along with your
+    // API process, for
+    // # example if you are using multiple cloud vendors, then it is recommended to
+    // set this to true.
+    // # webserver_https_enabled:
     @JsonProperty
     private boolean webserver_https_enabled = false;
 
@@ -191,9 +200,11 @@ public enum PASSWORD_HASHING_ALG {
     }
 
     public int getArgon2HashingPoolSize() {
-        // the reason we do Math.max below is that if the password hashing algo is bcrypt,
+        // the reason we do Math.max below is that if the password hashing algo is
+        // bcrypt,
         // then we don't check the argon2 hashing pool size config at all. In this case,
-        // if the user gives a <= 0 number, it crashes the core (since it creates a blockedqueue in PaswordHashing
+        // if the user gives a <= 0 number, it crashes the core (since it creates a
+        // blockedqueue in PaswordHashing
         // .java with length <= 0). So we do a Math.max
         return Math.max(1, argon2_hashing_pool_size);
     }
@@ -266,6 +277,15 @@ public long getPasswordlessCodeLifetime() {
         return passwordless_code_lifetime;
     }
 
+    public int getTotpMaxAttempts() {
+        return totp_max_attempts;
+    }
+
+    /** TOTP rate limit cooldown time (in seconds) */
+    public int getTotpRateLimitCooldownTimeSec() {
+        return totp_rate_limit_cooldown_sec;
+    }
+
     public boolean isTelemetryDisabled() {
         return disable_telemetry;
     }
@@ -384,6 +404,14 @@ void validateAndInitialise(Main main) throws IOException {
             throw new QuitProgramException("'passwordless_max_code_input_attempts' must be > 0");
         }
 
+        if (totp_max_attempts <= 0) {
+            throw new QuitProgramException("'totp_max_attempts' must be > 0");
+        }
+
+        if (totp_rate_limit_cooldown_sec <= 0) {
+            throw new QuitProgramException("'totp_rate_limit_cooldown_sec' must be > 0");
+        }
+
         if (max_server_pool_size <= 0) {
             throw new QuitProgramException("'max_server_pool_size' must be >= 1. The config file can be found here: "
                     + getConfigFileLocation(main));
@@ -475,4 +503,4 @@ void validateAndInitialise(Main main) throws IOException {
         }
     }
 
-}
+}