# Systém přihlašování MSPPPPaM – dokumentace pro implementaci

Tento dokument popisuje hotový systém přihlašování v PHP a MySQL,
který chci použít v novém projektu. Systém je připravený, neupravuj
jeho soubory – pouze ho používej.

---

## Umístění souborů

Všechny soubory systému jsou ve složce `auth/` v kořenovém adresáři projektu.

---

## Seznam souborů a jejich funkce

| Soubor | Popis |
|---|---|
| `auth/config.php` | Veškerá konfigurace systému (DB přihlašovací údaje, URL, limity, přepínače). Upravuje se při nasazení. |
| `auth/db.php` | Připojení k MySQL přes PDO. Výsledkem je proměnná `$pdo`. |
| `auth/auth.php` | Hlavní soubor – vkládá se na začátek chráněných stránek. Ověří přihlášení a nastaví proměnné (viz níže). |
| `auth/login.php` | Přihlašovací stránka s formulářem. Obsahuje ochranu proti brute force a CSRF. |
| `auth/logout.php` | Odhlášení – zruší session i remember me cookie. Přesměruje na login. |
| `auth/registrace.php` | Registrace nového uživatele (pokud je povolena v config.php). |
| `auth/reset_hesla.php` | Formulář pro zaslání odkazu na obnovu hesla emailem. |
| `auth/nove_heslo.php` | Stránka z odkazu v emailu – umožní zadat nové heslo. |
| `auth/admin.php` | Administrační rozhraní – správa uživatelů, zobrazení konfigurace, test emailu. Přístupné pouze adminům. |
| `auth/mail.php` | Pomocná funkce `odesli_mail()` pro odesílání emailů přes PHP `mail()`. |
| `auth/install.php` | Jednorázový instalační skript – vytvoří tabulky v DB a prvního admina. Po instalaci zablokován souborem `install.lock`. |
| `auth/js/heslo-sila.js` | JavaScript pro kontrolu síly hesla pomocí knihovny zxcvbn (Dropbox). Používají ho stránky s formuláři pro zadání hesla. |

---

## Jak použít systém na chráněné stránce

Na začátek každého PHP souboru, jehož obsah chci chránit, vložím:

```php
require_once 'auth/auth.php';
```

Po načtení jsou k dispozici tyto proměnné:

| Proměnná | Typ | Popis |
|---|---|---|
| `$auth_prihlasen` | `bool` | `true` pokud je uživatel přihlášen, jinak `false`. Nastaveno vždy. |
| `$auth_uzivatel['id']` | `int\|null` | ID přihlášeného uživatele, nebo `null` pokud není přihlášen. |
| `$auth_uzivatel['email']` | `string\|null` | Email přihlášeného uživatele, nebo `null`. |
| `$auth_uzivatel['admin']` | `bool` | `true` pokud je přihlášený uživatel admin, jinak `false`. Nastaveno vždy. |
| `$auth_logout_html` | `string` | Připravený HTML kód s emailem uživatele, tlačítkem odhlášení a (pro adminy) odkazem na administraci. Neprázdný pouze pokud je uživatel přihlášen. Použití: `echo $auth_logout_html;` |
| `$auth_login_html` | `string` | Připravený HTML formulář pro přihlášení (email, heslo, zapamatovat si mě, CSRF token). Neprázdný pouze pokud uživatel NENÍ přihlášen. Odesílá data na `login.php`, které po přihlášení přesměruje zpět na aktuální stránku. Použití: `echo $auth_login_html;` |

### Dva režimy fungování (nastavení v `auth/config.php`)

**`VYZADOVAT_PRIHLASENI = true`** (výchozí):
Nepřihlášený uživatel je automaticky přesměrován na přihlašovací stránku.
Na chráněnou stránku se dostane až po přihlášení.

**`VYZADOVAT_PRIHLASENI = false`**:
Stránka se zobrazí všem. Pomocí `$auth_prihlasen` si stránka sama
rozhodne, co nepřihlášenému uživateli ukáže.

---

## Databázové tabulky

Systém přihlašování vytváří a spravuje tyto tabulky:

### `auth_users` – uživatelé přihlašovacího systému

| Sloupec | Typ | Popis |
|---|---|---|
| `id` | `INT UNSIGNED` | Primární klíč, auto increment |
| `email` | `VARCHAR(255)` | Email uživatele, unikátní |
| `heslo` | `VARCHAR(255)` | Bcrypt hash hesla |
| `admin` | `TINYINT(1)` | 0 = běžný uživatel, 1 = admin |
| `vytvoreno` | `DATETIME` | Datum a čas registrace |

### `auth_remember_tokens` – tokeny pro "zapamatovat si mě"

Spravuje systém přihlašování automaticky. Není potřeba upravovat.

### `auth_brute_force` – záznamy neúspěšných přihlášení

Spravuje systém přihlašování automaticky. Není potřeba upravovat.

### `auth_password_resets` – tokeny pro obnovu hesla

Spravuje systém přihlašování automaticky. Není potřeba upravovat.

### `users` – uživatelé konkrétní služby

Tato tabulka propojuje systém přihlašování s tvým projektem.
Systém přihlašování ji vytvoří při instalaci se základní strukturou:

| Sloupec | Typ | Popis |
|---|---|---|
| `id` | `INT UNSIGNED` | Primární klíč, auto increment |
| `uzivatel_id` | `INT UNSIGNED` | Cizí klíč na `auth_users.id` (ON DELETE CASCADE) |

**Tuto tabulku rozšíříš o vlastní sloupce** podle potřeb projektu
(jméno, telefon, nastavení, apod.). Systém přihlašování ji nebude
nijak měnit – pouze při registraci nového uživatele do ní vloží
prázdný řádek s `uzivatel_id`.

Propojení s uživatelem přihlašovacího systému:
```sql
SELECT u.*, au.email
FROM users u
JOIN auth_users au ON au.id = u.uzivatel_id
WHERE u.uzivatel_id = :id
```

---

## Konfigurace (auth/config.php)

Při nasazení do projektu je potřeba vyplnit:

- `DB_HOST`, `DB_NAME`, `DB_USER`, `DB_PASS` – přihlašovací údaje k MySQL
- `PROJEKT_NAZEV` – název projektu (zobrazuje se na přihlašovací stránce)
- `PROJEKT_URL` – základní URL webu (používá se v odkazech v emailech)
- `MAIL_ODESILATEL` – emailová adresa odesílatele (musí být autorizována SPF záznamem domény)
- `MAIL_TEST_ADRESA` – adresa pro testovací email v admin rozhraní
- `REGISTRACE_OTEVRENA` – `true` = veřejná registrace, `false` = pouze admin zakládá uživatele
- `VYZADOVAT_PRIHLASENI` – `true` = přesměrovat nepřihlášené, `false` = stránka rozhoduje sama

Cesty ke stránkám auth systému (pokud je složka `auth/` jinde než v kořeni webu):
- `AUTH_LOGIN_URL`, `AUTH_LOGOUT_URL`, `AUTH_ADMIN_URL`
- `AUTH_REGISTRACE_URL`, `AUTH_RESET_URL`
- `AUTH_REDIRECT_PO_PRIHLASENI` – kam přesměrovat po přihlášení

---

## Bezpečnostní vlastnosti systému

Pro přehled – systém řeší:
- Hesla hashována bcryptem (`password_hash` s `PASSWORD_DEFAULT`)
- Ochrana před SQL injection – výhradně PDO prepared statements
- Ochrana před CSRF – každý formulář obsahuje token ověřovaný na serveru
- Ochrana před brute force – blokování po opakovaných neúspěšných pokusech
- Ochrana před session fixation – `session_regenerate_id()` při přihlášení
- Ochrana před XSS – `htmlspecialchars()` na všech výstupech
- Remember me – bezpečný selector+token mechanismus (heslo ani ID není v cookie)
- Síla hesla – kontrola přes zxcvbn (JavaScript) + minimální délka (PHP)
- Celá DB v `utf8mb4` – plná podpora diakritiky a emoji