# PlusFacility.cz auth.md

Objevovací dokument (discovery document) pro registraci, autentizaci a autorizaci autonomních AI agentů pro platformu **PlusFacility.cz** (`https://plusfacility.cz`).

---

## 1. Cílová skupina agentů (Agent Audience)

Tento portál a související API/MCP rozhraní slouží pro:
- **Facility Management & Asistenční AI agenty** provádějící příjem a třídění hlášení závad v nájemních nemovitostech.
- **Asistenty nájemníků** pomáhající obyvatelům jednotek sledovat průběh oprav, potvrzovat termíny návštěv a předávat zpětnou vazbu.
- **Dispečerské a ERP agenty** koordinující síť řemeslníků, schvalování položkových rozpočtů a exporty nákladů.
- **QA a auditní roboty** ověřující dostupnost, bezpečnost a dodržování webových standardů.

---

## 2. Objevovací rozhraní (Discovery Endpoints)

- **API Catalog (RFC 9727):** `GET /.well-known/api-catalog`
- **MCP Server Card:** `GET /.well-known/mcp/server-card.json`
- **A2A Agent Card:** `GET /.well-known/agent-card.json`
- **AI Resource Discovery (ARD):** `GET /.well-known/ai-catalog.json`
- **Auth.md Specifikace:** `GET /auth.md`
- **OpenAPI 3.1 Specifikace:** `GET /openapi.json`

---

## 3. Registrace a autentizační toky agentů

### 3.1 Podporované typy identit (Identity Types)
- **`anonymous`**: Určeno pro nájemníky a veřejné hlášení závad přes QR štítek jednotky (`/qr/[token]`). Nevyžaduje přihlašovací údaje. Pro následné opakované sledování průběhu opravy se používá časově omezený hashovaný sledovací odkaz (`/sledovat/[token]`) nebo hlavička `x-tracking-token` na koncovém bodu detailu opravy.
- **`session_cookie`**: Přihlášení registrovaných uživatelů (dispečeři, pronajímatelé, správci, schvalovatelé, účetní, technici) přes `POST /api/auth/login`. Vydává podepsanou `HttpOnly` cookie `pf_session`. Účty s aktivovaným 2FA (RFC 6238 TOTP) vyžadují před vydáním `pf_session` platný 6místný kód `totpCode`.

### 3.2 Koncové body autentizace a správy účtu
- **Login URI:** `https://plusfacility.cz/prihlaseni`
- **Token / Session Endpoint:** `https://plusfacility.cz/api/auth/login`
- **Logout Endpoint:** `https://plusfacility.cz/api/auth/logout`
- **Session Inspection:** `https://plusfacility.cz/api/auth/me`
- **Account & 2FA Management:** `https://plusfacility.cz/ucet` (`POST /api/auth/change-password`)
- **Password Reset:** `https://plusfacility.cz/zapomenute-heslo` (`POST /api/auth/forgot-password`, `POST /api/auth/reset-password`)
- **Credential Types:** `session_cookie` (`pf_session`), `tracking_token` (`x-tracking-token` pro nájemníky)
- **Credential Usage:** Zabezpečená serverová cookie `pf_session` (pro přihlášené role) nebo hlavička `x-tracking-token` / `/sledovat/[token]` (pro nájemníky).

---

## 4. Typy oprávnění a rolí v systému

Data každé organizace jsou v platformě striktně oddělená. Přístup přes `POST /api/auth/login` se řídí přidělenou globální a týmovou rolí účtu:

| Role v systému | Způsob autentizace | Rozsah oprávnění |
|---|---|---|
| Administrátor / Dispečer | Přihlašovací účet (silné heslo + volitelné TOTP 2FA) | Posouzení hlášení, kalkulace nabídek, přiřazení techniků |
| Pronajímatel / Správce / Schvalovatel / Účetní | Přihlašovací účet organizace (+ volitelné TOTP 2FA) | Správa vlastních nemovitostí, jednotek, nájemníků, QR štítků, exporty nákladů a schvalování oprav dle týmové role |
| Servisní technik | Přihlašovací účet technika (+ volitelné TOTP 2FA) | Návrh termínů návštěv, zahájení práce, zápis práce, materiálu a fotodokumentace |
| Nájemník (obyvatel jednotky) | Kód QR štítku / Sledovací odkaz | Bez účtu: nahlášení závady a sledování stavu opravy přes sledovací odkaz (`/sledovat/[token]`) |

*Poznámka: V produkčním prostředí je testovací přepínání rolí vypnuté (`DEMO_MODE=false`) a žádné výchozí ani sdílené účty nejsou aktivní.*