diff --git a/pomocne/prompt.md b/pomocne/prompt.md new file mode 100644 index 0000000..9c9461d --- /dev/null +++ b/pomocne/prompt.md @@ -0,0 +1,146 @@ +# 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 \ No newline at end of file