# BackendJoinGuard

![Plugin](https://img.shields.io/badge/Plugin-BackendJoinGuard-0B63CE?style=for-the-badge)
![Platform](https://img.shields.io/badge/Platform-Paper%20%2F%20Spigot-D48700?style=for-the-badge)
![Mode](https://img.shields.io/badge/Mode-Standalone%20or%20StatusAPI%20Sync-6F42C1?style=for-the-badge)

BackendJoinGuard blockiert direkte Joins auf Backend-Servern und erlaubt nur Verbindungen vom Proxy.

Wichtig:
- Dieses Plugin kommt auf jeden Backend-Server.
- Es kommt nicht auf den Proxy.
- Es kann komplett eigenständig genutzt werden.
- Optional kann es seine Regeln zentral von StatusAPI beziehen.

## Zweck

BackendJoinGuard verhindert, dass Spieler einen Unterserver direkt betreten und damit den Proxy-Schutz umgehen.

Das Plugin prüft beim Login die Quell-IP des Spielers.
Nur erlaubte Proxy-IPs oder CIDR-Netze dürfen durchgelassen werden.
Alle anderen Verbindungen werden direkt vor dem Join geblockt.

## Betriebsarten

### Standalone

BackendJoinGuard nutzt nur seine eigene config.yml.
Das ist sinnvoll, wenn du keinen zentralen Sync willst oder das Plugin unabhängig von StatusAPI betreiben möchtest.

### StatusAPI Sync

BackendJoinGuard lädt seine Schutzregeln regelmäßig von StatusAPI.
Wenn der Sync ausfällt, bleiben die lokalen Werte aus der config.yml als Fallback erhalten.

## Installation

1. Die JAR in den plugins-Ordner jedes Backend-Servers kopieren.
2. Server starten, damit die config.yml erzeugt wird.
3. Konfiguration anpassen.
4. Server neu starten oder /backendguard reload ausführen.

## Konfiguration

Datei: config.yml

### Lokale Guard-Werte

- enforcement-enabled
  Aktiviert oder deaktiviert den Direktjoin-Schutz.

- log-blocked-attempts
  Loggt geblockte Direktjoin-Versuche in die Konsole.

- kick-message
  Nachricht für geblockte Spieler.

- allowed-proxy-ips
  Liste exakter Proxy-IPs.

- allowed-proxy-cidrs
  Liste erlaubter Netze im CIDR-Format.

Beispiel:

```yml
enforcement-enabled: true
log-blocked-attempts: true
kick-message: "&cBitte verbinde dich nur ueber den Proxy-Server."

allowed-proxy-ips:
  - "127.0.0.1"
  - "::1"
  - "185.123.45.67"

allowed-proxy-cidrs:
  - "10.0.0.0/24"
```

### StatusAPI Sync

Konfigurationsblock:

```yml
statusapi-sync:
  enabled: true
  base-url: "http://127.0.0.1:9191"
  endpoint-path: "/network/backendguard/config"
  api-key: "DEIN_SYNC_KEY"
  interval-seconds: 60
  log-sync-errors: true
```

Bedeutung:

- enabled
  Aktiviert den zentralen Abruf über StatusAPI.

- base-url
  Basis-URL deiner StatusAPI auf dem Proxy.

- endpoint-path
  Standard-Endpunkt für den Guard-Sync.

- api-key
  Optionaler Schutz für den Sync-Endpunkt.
  Muss identisch zu backendguard.sync.api_key in StatusAPI sein.

- interval-seconds
  Wie oft BackendJoinGuard die Regeln neu abruft.

- log-sync-errors
  Loggt Sync-Probleme in die Backend-Konsole.

## Passende StatusAPI-Konfiguration

Wenn du den Sync-Modus nutzen willst, pflegst du die zentralen Werte in StatusAPI über network-guard.properties.

Relevante Schlüssel:

```properties
backendguard.enforcement_enabled=true
backendguard.log_blocked_attempts=true
backendguard.kick_message=&cBitte verbinde dich nur ueber den Proxy-Server.
backendguard.allowed_proxy_ips=127.0.0.1,::1,185.123.45.67
backendguard.allowed_proxy_cidrs=10.0.0.0/24
backendguard.sync.api_key=DEIN_SYNC_KEY
```

## Beispiele

### Alles auf einer Maschine

Nutze in der Regel:

- allowed-proxy-ips: 127.0.0.1, ::1
- base-url: http://127.0.0.1:9191

### Proxy auf einem anderen Host

Nutze die echte Proxy-IP:

- allowed-proxy-ips: 185.123.45.67
- base-url: http://185.123.45.67:9191

### Internes Netzwerk

Nutze interne IP oder CIDR:

- allowed-proxy-ips: 10.0.0.10
- allowed-proxy-cidrs: 10.0.0.0/24
- base-url: http://10.0.0.10:9191

## Befehl

| Command | Beschreibung |
|---|---|
| /backendguard reload | Lädt die Config neu und startet bei aktivem Sync sofort einen neuen Abruf |

## Permission

| Permission | Beschreibung |
|---|---|
| backendguard.admin | Darf BackendJoinGuard verwalten |

## Funktionsweise

BackendJoinGuard prüft beim PreLogin die IP-Adresse des Clients.

- Erlaubte Proxy-IP: Join erlaubt
- Erlaubtes CIDR-Netz: Join erlaubt
- Alles andere: Join wird direkt geblockt

## Troubleshooting

### Spieler werden trotz Proxy geblockt

- Prüfe, ob wirklich die Proxy-IP in allowed-proxy-ips eingetragen ist.
- Prüfe bei mehreren Netzsegmenten, ob ein CIDR-Eintrag sinnvoller ist.
- Prüfe, ob Velocity/Bungee korrekt als vorgeschalteter Proxy arbeitet.

### Sync mit StatusAPI funktioniert nicht

- Prüfe base-url.
- Prüfe, ob StatusAPI auf dem konfigurierten Port erreichbar ist.
- Prüfe, ob api-key identisch zu backendguard.sync.api_key ist.
- Prüfe die Backend-Konsole bei aktiviertem log-sync-errors.

### Standalone oder Sync?

- Wenn du maximale Einfachheit willst: Standalone.
- Wenn du zentrale Verwaltung willst: StatusAPI Sync.
- Wenn StatusAPI ausfällt, bleiben im Sync-Modus die lokalen Werte als Absicherung bestehen.