DownAuth

# DownAuth Fallback authentication for Velocity proxy with strong, configurable security controls when Mojang auth is unavailable. ## Overview - **Purpose**: Allow trusted players to join using their cached session if Mojang authentication is down. - **How**: Switches to offline-mode for the affected connection, validates against a cached session, and applies layered security checks to reduce spoofing risk. ## Key Features - **Fallback authentication** - Uses cached session data: UUID, username, last known IP, timestamps, GameProfile properties (skin/cape). - Automatically activates when Mojang auth appears down; reverts when back up. - **Service health monitoring** - Periodic checks drive fallback enable/disable logic. - Tunable health check interval and failure threshold. - **Audit logging (optional)** - Writes security events (fallback used, geo/ASN change, PIN prompts) to `audit.log`. - **IP validation with IPv6 support** - Strict IP match by default. - Optional network range matching with configurable CIDR for IPv4 and IPv6. - **Geo/ASN checks** - Looks up the country code and ASN of the connecting IP. - Alerts staff on large changes; can optionally deny fallback until a normal online-mode login occurs again. - ASN blocklist to deny known hosting/VPN networks during fallback. - Provider URL, timeout, and response cache TTL are configurable. - **Rate limiting** - Per-IP and per-UUID attempt throttling. - Extended throttling per-subnet and per-ASN to slow broad spoof attempts. - **PIN verification during outages (optional)** - Require players to set a PIN during normal operation; when fallback is used, they must verify with `/pin <code>` within a timeout. - Players are reminded on join to set a PIN if the policy requires it and they don’t have one yet. - PINs are stored hashed (SHA-256) in the cached session. - **Admin alerts** - Notify players with `downauth.alert` when fallback is used or when a geo/ASN change is detected. - **Storage** - JSON on-disk session storage with optional cleanup on startup. ## Commands - `/setpin <code>` - Sets a personal fallback PIN (minimum length configurable). - `/pin <code>` - If a verification is pending (during fallback), verifies the code. - If no verification is pending, sets the PIN as a convenience. - `/resetpin` - Clears your PIN only when Mojang auth is healthy (online-mode path). ## Permissions - **downauth.alert** - Receive staff alerts about fallback usage and geo/ASN changes. - Commands do not enforce additional permissions by default. Use your proxy’s permission system if you want to restrict them. ## Configuration (excerpt) ```yaml session-cache: max-session-age: 72 storage-type: "JSON" strict-ip-check: true allow-ip-range-match: true ipv4-range-prefix: 24 ipv6-range-prefix: 64 cleanup-on-startup: true security: min-login-history: 3 max-failed-attempts: 10 failure-ban-duration: 30 require-recent-activity: true recent-activity-days: 30 alert-on-fallback: true enable-geo-checks: true alert-on-geo-change: true deny-on-geo-change: false require-pin-on-fallback: false pin-timeout-seconds: 60 pin-min-length: 6 max-failed-attempts-per-subnet: 30 max-failed-attempts-per-asn: 100 blocked-asns: require-mojang-auth: # UUIDs that must always authenticate online monitoring: health-check-interval: 30 failure-threshold: 3 enable-statistics: true enable-metrics: true enable-audit-log: true geo-lookup-timeout: 2000 geo-provider-url: "https://ipwho.is/{ip}?fields=ip,country_code,connection" geo-cache-ttl: 300 messages: fallback-auth-active: "&eAuthentication servers are down. Using cached session." fallback-auth-failed: "&cCannot authenticate: No cached session found." session-expired: "&cYour session has expired. Please try again when auth servers are online." mojang-down-notice: "&7Mojang authentication servers appear to be down." pin-prompt: "&ePlease verify your identity: use &6/pin <code>&e within &6%timeout%s" pin-success: "&aVerification successful." pin-failure: "&cIncorrect PIN." pin-required-notice: "&ePins are required during auth outages. Set your PIN with &6/setpin <code>&e." geo-denied: "&cConnection denied due to location or network change. Please try again later." ``` ## Security messages and when they appear - **fallback-auth-active**: Sent to staff with `downauth.alert` when fallback is used. - **fallback-auth-failed**: Sent to the player if no cached session exists while in fallback. - **session-expired**: Sent to the player if their cached session is too old or invalid. - **mojang-down-notice**: General heads-up when services seem to be down (used by the plugin in appropriate places). - **pin-prompt**: Direct message to a player who must verify their PIN during fallback; they must run `/pin <code>` before the timeout. - **pin-success / pin-failure**: Results of PIN verification. - **pin-required-notice**: