AltDetector Plugin

# 🔍 AltDetector **Intelligent Alternate Account Detection for Paper** Stop ban evasion in its tracks. AltDetector runs a silent, fully async multi-layer detection engine on every login — no lag, no false positives flooding chat, just precise alerts delivered straight to your staff. --- ## ✨ Features ### 🧠 Multi-Layer Detection Engine Every login is analyzed through four independent detection layers, each producing a confidence score that is then weighted and combined into a final **risk score (0. 0–1.0)**: | Layer | Method | Weight | |---|---|---| | **IP Match** | Shared IP address history | 40% | | **UUID / Username History** | Name-swap & cross-account username collisions | 25% | | **Login Pattern Analysis** | Session shifts, never-concurrent play, rapid alternation | 25% | | **Behavior Fingerprint** | Playtime ratios, peak-hour cosine similarity | 10% | All detection runs **fully asynchronously** — the main thread is never blocked. ### ⚠️ Smart Risk Thresholds | Score | Level | Action | |---|---|---| | 0.50 – 0.69 | 🟡 LOW | Staff alert only | | 0.70 – 0.84 | 🟠 MEDIUM | Staff alert + flag player record | | 0.85 – 1.00 | 🔴 HIGH | Staff alert + flag + optional auto-ban | All thresholds are fully configurable. ### 📣 Interactive Staff Alerts Alerts are silently sent only to players with `altdetector.staff.alerts`. Each alert includes clickable ** ** buttons — no need to type a single command. Offline staff receive queued alerts the moment they log in. ### 🔨 Auto-Ban System When an alt of a **banned player** is detected above your configured threshold, AltDetector can automatically issue a ban with a customizable reason and appeal URL. Fires a cancellable `AltBanEvent` so other plugins can hook in. ### 🗄️ SQLite Storage (Async, WAL Mode) All data is stored in a local **SQLite database** using WAL journal mode and prepared statements. Tracked data includes: - IP address history (up to 20 per player, FIFO) - Username history (up to 50, FIFO) - Risk scores & flagged status - Staff notes - Full detection log with evidence tags ### 🛡️ Privacy & Fairness Tools - **IP Anonymization** — store only partial IPs (first 3 octets) for GDPR compliance - **Shared IP Groups** — whitelist households/LAN players so they're never flagged - **VPN/Proxy Hints** — detects datacenter IP ranges (configurable CIDR list) and adds a `vpn_hint` evidence tag with a small risk bump - **Bypass Permission** — grant `altdetector.bypass` to trusted accounts ### 🖥️ Commands | Command | Description | |---|---| | `/alt <player> ` | View all known alts of a player with risk scores | | `/altadmin inspect <player>` | Full profile: IPs, logins, risk, links, evidence | | `/altadmin history <player>` | Paginated login history with timestamps | | `/altadmin link <p1> <p2>` | Manually link two accounts | | `/altadmin unlink <p1> <p2>` | Remove a link | | `/altadmin confirm <player>` | Confirm a detected alt link | | `/altadmin whitelist <player>` | Whitelist from detection | | `/altadmin ban <player>` | Ban player and all confirmed alts simultaneously | | `/altadmin note <player> <text>` | Attach a staff note | | `/altadmin purge <player>` | Full GDPR data wipe | | `/altadmin export <player>` | Export full record as JSON | | `/altadmin stats` | Detection statistics | | `/altadmin reload` | Hot-reload config & messages | All subcommands support **tab-completion**. ### 🔌 PlaceholderAPI Support | Placeholder | Value | |---|---| | `%altdetector_risk_score%` | Player's current risk score | | `%altdetector_alt_count%` | Number of known alt accounts | | `%altdetector_flagged%` | `true` or `false` | ### 🪝 Custom API Events Other plugins can hook into AltDetector's pipeline: - `AltDetectedEvent` — fired on any detection above LOW threshold - `AltBanEvent` *(cancellable)* — fired before any auto-ban - `AltLinkConfirmedEvent` — fired when staff confirms a link - `AltWhitelistEvent` — fired on whitelist changes --- ## 📦 Requirements - **Paper** 1.21+ - **Java 21** - PlaceholderAPI *(optional, soft-depend)* ## ⚙️ Configuration Fully documented `config.yml` and MiniMessage-powered `messages.yml` with named placeholders. Reload at any time with `/altadmin reload` — no restart needed. --- *AltDetector is designed for survival, SMP, factions, and competitive servers where ban evasion is a serious problem. Zero dependencies beyond Paper itself.*