first commit

README.md

@@ -0,0 +1,64 @@
+# TS3 monolith (Go)
+
+Jedna aplikacja zastępująca stare `sk.linuxiarz.pl` i `ts3stats`.
+
+## Zachowana funkcjonalność
+
+- wykrycie klienta TeamSpeak po IP widzianym przez HTTP i ServerQuery;
+- utworzenie permanentnego kanału z nazwą, tematem i opcjonalnym hasłem;
+- `setclientchannelgroup` dla wskazanego `client_database_id`;
+- `clientmove` wskazanego `clid` do nowego kanału;
+- obecna baza RRD `online` i wykresy: 12h, 24h, 72h, tydzień, miesiąc, rok;
+- formularz pod `/embed/channel`, przeznaczony do osadzenia na innej domenie.
+
+Przy jednym kliencie pod danym IP wszystko działa automatycznie. Jeżeli kilka klientów TS3 ma ten sam publiczny IP (NAT), aplikacja prosi o wybór nicku i wysyła 6-cyfrowy kod prywatną wiadomością TS3. Dzięki temu nie przenosi przypadkowej osoby i nie nadaje jej Channel Admina.
+
+## Uruchomienie
+
+1. Skopiuj `.env.example` do `.env` i ustaw sekrety oraz dozwoloną domenę iframe.
+2. Zachowaj `data/linuxiarz.rrd`. To kopia dotychczasowej bazy z archiwum.
+3. Zapewnij zapis do katalogu `data` dla UID 10001 przy Dockerze: `chown -R 10001:10001 data`.
+4. Uruchom: `docker compose up -d --build`.
+5. Reverse proxy kieruje HTTPS do `127.0.0.1:8080`.
+
+Przykład iframe:
+
+```html
+<iframe
+  src="https://app.example.org/embed/channel"
+  title="Utwórz kanał TeamSpeak"
+  loading="lazy"
+  referrerpolicy="no-referrer"
+  style="width:100%;min-height:620px;border:0">
+</iframe>
+```
+
+`FRAME_ANCESTORS` musi zawierać origin strony nadrzędnej, np. `https://www.example.org`.
+
+## TeamSpeak ServerQuery
+
+Najbezpieczniej uruchamiać aplikację na tym samym hoście lub w prywatnej sieci z TS3 i ustawić `TS_QUERY_HOST=127.0.0.1`/adres prywatny. Nie wystawiaj portu 10011 publicznie. Query powinien mieć tylko prawa potrzebne do: `clientlist -ip -uid`, `channelcreate`, `setclientchannelgroup`, `clientmove`, `sendtextmessage`, `channeldelete` (rollback).
+
+## RRD
+
+Aplikacja używa systemowego `rrdtool`, a nie biblioteki Go, więc istniejący plik RRD pozostaje bez migracji. Co 60 s liczona jest liczba klientów `client_type=0` na wybranym virtual serverze i zapisywana do DS `online`. Błąd ServerQuery nie zapisuje sztucznego zera.
+
+Jeżeli docelowy serwer ma inną architekturę/endianness niż źródłowy x86_64 little-endian, przenieś RRD przez `rrdtool dump`/`rrdtool restore` zamiast kopiowania binarnego pliku.
+
+## Bezpieczeństwo / fingerprinting
+
+- brak PHP, frameworków frontendowych, CDN i nagłówka `X-Powered-By`;
+- standardowy `net/http` nie dodaje nagłówka `Server`;
+- CSP z kontrolowanym `frame-ancestors`, HSTS, `nosniff`, restrykcyjne Permissions-Policy;
+- nagłówki proxy są ufane wyłącznie z `TRUSTED_PROXIES`;
+- stateless HMAC tokeny formularzy i klientów, sprawdzanie `Origin`, limity request body i rate limiting;
+- sekrety tylko przez środowisko, brak danych dostępowych w repo;
+- rollback kanału, jeśli nadanie grupy lub przeniesienie klienta się nie powiedzie;
+- kontener non-root, `cap_drop: ALL`, `no-new-privileges`, read-only root filesystem;
+- build z `-trimpath` i usuniętymi symbolami/debug info.
+
+Nie da się zagwarantować, że stos technologiczny będzie całkowicie nierozpoznawalny na podstawie zachowania sieci/TLS. Celem jest brak prostych bannerów, wersji i sygnatur frameworka.
+
+## Ważne po migracji
+
+W dostarczonym archiwum stare aplikacje mają dane logowania ServerQuery wpisane bezpośrednio w PHP. Zmień hasło konta Query po wdrożeniu i nie kopiuj starego sekretu do repozytorium.