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)

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 &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 &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**: Reminds players (on join) to set a PIN when policy requires pins during outages and they don’t have one yet.
- **geo-denied**: Disconnect reason if policy denies fallback on geo/ASN change while services are down.

## How it works (high level)
1. **PreLogin**: If Mojang auth appears down, the connection is switched to offline-mode and validated against the cached session with IP/rate/geo/ASN checks.
2. **GameProfileRequest**: Supplies a profile built from the cached session (UUID, name, properties).
3. **PostLogin**: Updates the session, re-checks geo/ASN, alerts staff if needed, and optionally enforces PIN verification.

## Geo provider
- Default provider: `ipwho.is` (no key required). You can change the provider URL and tune timeouts and TTL in `monitoring`.

## Notes
- This plugin is designed for Velocity proxy environments. Place the jar into the proxy’s `plugins/` folder. Adjust `config.yml` as needed, then restart the proxy.
- If you enable PINs, ensure players set their PINs while authentication is healthy to avoid disruption when outages occur.