Add API for alt detection and account management (#162)

bans-api/src/main/java/space/arim/libertybans/api/LibertyBans.java

@@ -1,23 +1,25 @@
-/* 
- * LibertyBans-api
- * Copyright © 2020 Anand Beh <https://www.arim.space>
- * 
- * LibertyBans-api is free software: you can redistribute it and/or modify
+/*
+ * LibertyBans
+ * Copyright © 2023 Anand Beh
+ *
+ * LibertyBans is free software: you can redistribute it and/or modify
  * it under the terms of the GNU Affero General Public License as
  * published by the Free Software Foundation, either version 3 of the
  * License, or (at your option) any later version.
- * 
- * LibertyBans-api is distributed in the hope that it will be useful,
+ *
+ * LibertyBans is distributed in the hope that it will be useful,
  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  * GNU Affero General Public License for more details.
- * 
+ *
  * You should have received a copy of the GNU Affero General Public License
- * along with LibertyBans-api. If not, see <https://www.gnu.org/licenses/>
+ * along with LibertyBans. If not, see <https://www.gnu.org/licenses/>
  * and navigate to version 3 of the GNU Affero General Public License.
  */
+
 package space.arim.libertybans.api;
 
+import space.arim.libertybans.api.user.AccountSupervisor;
 import space.arim.omnibus.Omnibus;
 import space.arim.omnibus.util.concurrent.FactoryOfTheFuture;
 
@@ -103,4 +105,11 @@ public interface LibertyBans {
 	 */
 	UserResolver getUserResolver();
 
+	/**
+	 * Gets the account supervisor for alt detection and management
+	 *
+	 * @return the account supervisor
+	 */
+	AccountSupervisor getAccountSupervisor();
+
 }

bans-api/src/main/java/space/arim/libertybans/api/user/AccountBase.java

@@ -0,0 +1,54 @@
+/*
+ * LibertyBans
+ * Copyright © 2023 Anand Beh
+ *
+ * LibertyBans is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as
+ * published by the Free Software Foundation, either version 3 of the
+ * License, or (at your option) any later version.
+ *
+ * LibertyBans is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with LibertyBans. If not, see <https://www.gnu.org/licenses/>
+ * and navigate to version 3 of the GNU Affero General Public License.
+ */
+
+package space.arim.libertybans.api.user;
+
+import space.arim.libertybans.api.NetworkAddress;
+
+import java.util.Optional;
+import java.util.UUID;
+
+/**
+ * Base interface for accounts
+ *
+ */
+public interface AccountBase {
+
+	/**
+	 * The account UUID
+	 *
+	 * @return the UUID
+	 */
+	UUID uuid();
+
+	/**
+	 * The latest username for the corresponding user, if it is known
+	 *
+	 * @return the latest username if there is one
+	 */
+	Optional<String> latestUsername();
+
+	/**
+	 * The account address
+	 *
+	 * @return the address
+	 */
+	NetworkAddress address();
+
+}

bans-api/src/main/java/space/arim/libertybans/api/user/AccountSupervisor.java

@@ -0,0 +1,68 @@
+/*
+ * LibertyBans
+ * Copyright © 2023 Anand Beh
+ *
+ * LibertyBans is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as
+ * published by the Free Software Foundation, either version 3 of the
+ * License, or (at your option) any later version.
+ *
+ * LibertyBans is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with LibertyBans. If not, see <https://www.gnu.org/licenses/>
+ * and navigate to version 3 of the GNU Affero General Public License.
+ */
+
+package space.arim.libertybans.api.user;
+
+import space.arim.libertybans.api.NetworkAddress;
+import space.arim.omnibus.util.concurrent.CentralisedFuture;
+
+import java.util.List;
+import java.util.UUID;
+
+/**
+ * Enables detecting alts leveraging all the capabilities provided by the implementation
+ *
+ */
+public interface AccountSupervisor {
+
+	/**
+	 * Begins to detects alts for the given player
+	 *
+	 * @param uuid the player's UUID
+	 * @param address the player's address
+	 * @return a detection query builder
+	 */
+	DetectionQuery.Builder detectAlts(UUID uuid, NetworkAddress address);
+
+	/**
+	 * Finds accounts matching the given UUID
+	 *
+	 * @param uuid the uuid
+	 * @return all matching accounts
+	 */
+	CentralisedFuture<List<? extends KnownAccount>> findAccountsMatching(UUID uuid);
+
+	/**
+	 * Finds accounts matching the given address
+	 *
+	 * @param address the address
+	 * @return all matching accounts
+	 */
+	CentralisedFuture<List<? extends KnownAccount>> findAccountsMatching(NetworkAddress address);
+
+	/**
+	 * Finds accounts matching the given UUID or address
+	 *
+	 * @param uuid the uuid
+	 * @param address the address
+	 * @return all accounts matching the UUID OR the address
+	 */
+	CentralisedFuture<List<? extends KnownAccount>> findAccountsMatching(UUID uuid, NetworkAddress address);
+
+}

bans-api/src/main/java/space/arim/libertybans/api/user/AltAccount.java

@@ -0,0 +1,49 @@
+/*
+ * LibertyBans
+ * Copyright © 2023 Anand Beh
+ *
+ * LibertyBans is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as
+ * published by the Free Software Foundation, either version 3 of the
+ * License, or (at your option) any later version.
+ *
+ * LibertyBans is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with LibertyBans. If not, see <https://www.gnu.org/licenses/>
+ * and navigate to version 3 of the GNU Affero General Public License.
+ */
+
+package space.arim.libertybans.api.user;
+
+import space.arim.libertybans.api.PunishmentType;
+
+import java.time.Instant;
+
+/**
+ * A detected alt account
+ *
+ */
+public interface AltAccount extends AccountBase {
+
+	/**
+	 * The most recent time this alt was observed
+	 *
+	 * @return the last time this alt account was observed
+	 */
+	Instant lastObserved();
+
+	/**
+	 * Whether the alt account has ANY active punishments of the specified type
+	 *
+	 * @param type the punishment type
+	 * @return true if a punishment with the type exists and is active
+	 * @throws IllegalArgumentException if the type was not queried for in the {@link DetectionQuery}
+	 * (note this exception is not guaranteed to be thrown, false may be returned instead)
+	 */
+	boolean hasActivePunishment(PunishmentType type);
+
+}

bans-api/src/main/java/space/arim/libertybans/api/user/DetectionQuery.java

@@ -0,0 +1,103 @@
+/*
+ * LibertyBans
+ * Copyright © 2023 Anand Beh
+ *
+ * LibertyBans is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as
+ * published by the Free Software Foundation, either version 3 of the
+ * License, or (at your option) any later version.
+ *
+ * LibertyBans is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with LibertyBans. If not, see <https://www.gnu.org/licenses/>
+ * and navigate to version 3 of the GNU Affero General Public License.
+ */
+
+package space.arim.libertybans.api.user;
+
+import space.arim.libertybans.api.NetworkAddress;
+import space.arim.libertybans.api.PunishmentType;
+import space.arim.omnibus.util.concurrent.CentralisedFuture;
+
+import java.util.List;
+import java.util.Set;
+import java.util.UUID;
+
+/**
+ * Query to detect alts
+ *
+ */
+public interface DetectionQuery {
+
+	/**
+	 * The uuid of the player whose alts to search for
+	 *
+	 * @return the uuid
+	 */
+	UUID uuid();
+
+	/**
+	 * The network address of the player whose alts to search for
+	 *
+	 * @return the address
+	 */
+	NetworkAddress address();
+
+	/**
+	 * The punishment types to scan alts for
+	 *
+	 * @return the punishment types
+	 */
+	Set<PunishmentType> punishmentTypes();
+
+	/**
+	 * Builder for detection queries
+	 *
+	 */
+	interface Builder {
+
+		/**
+		 * The punishment types to scan alts for. <br>
+		 * <br>
+		 * If enabled, the alt detection will attempt to look for punishment types applying to the specified
+		 * alts on a best effort basis.
+		 *
+		 * @param types the punishment types to match alts with
+		 * @return this builder
+		 */
+		default Builder punishmentTypes(PunishmentType...types) {
+			return punishmentTypes(Set.of(types));
+		}
+
+		/**
+		 * The punishment types to scan alts for. <br>
+		 * <br>
+		 * If enabled, the alt detection will attempt to look for punishment types applying to the specified
+		 * alts on a best effort basis.
+		 *
+		 * @param types the punishment types to match alts with
+		 * @return this builder
+		 */
+		Builder punishmentTypes(Set<PunishmentType> types);
+
+		/**
+		 * Builds into a detection query
+		 *
+		 * @return the detection query
+		 */
+		DetectionQuery build();
+
+	}
+
+	/**
+	 * Performs the detection
+	 *
+	 * @return a future yielding the alt accounts
+	 */
+	CentralisedFuture<List<? extends AltAccount>> detect();
+
+}

bans-api/src/main/java/space/arim/libertybans/api/user/KnownAccount.java

@@ -0,0 +1,47 @@
+/*
+ * LibertyBans
+ * Copyright © 2023 Anand Beh
+ *
+ * LibertyBans is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as
+ * published by the Free Software Foundation, either version 3 of the
+ * License, or (at your option) any later version.
+ *
+ * LibertyBans is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with LibertyBans. If not, see <https://www.gnu.org/licenses/>
+ * and navigate to version 3 of the GNU Affero General Public License.
+ */
+
+package space.arim.libertybans.api.user;
+
+import space.arim.omnibus.util.concurrent.CentralisedFuture;
+
+import java.time.Instant;
+
+/**
+ * A known login for a certain player
+ *
+ */
+public interface KnownAccount extends AccountBase {
+
+	/**
+	 * When the login took place
+	 *
+	 * @return the time the login was recorded
+	 */
+	Instant recorded();
+
+	/**
+	 * Attempts to delete this known account
+	 *
+	 * @return a future yielding true if deleted, false if it does not exist
+	 * (perhaps because it was deleted by another instance)
+	 */
+	CentralisedFuture<Boolean> deleteFromHistory();
+
+}