Přístup k interní dokumentaci

V produkci jsou chráněné všechny soubory pod /docs/, Swagger UI pod /api/docs a OpenAPI JSON /api/docs.json. Health, běžné aplikační API a veřejná loga tato brána neovlivňuje.

Přístup člověka

1. Nepřihlášený browser je přesměrován na ZITADEL.
2. API používá OIDC klienta již existující aplikace auth; nevzniká nový klient.
3. Po callbacku se kromě podpisu ZITADEL tokenu ověří panel.access v User API.
4. Browser dostane podepsanou HttpOnly, Secure, SameSite=Lax cookie pouze pro dokumentaci. Produkční session platí 8 hodin.

V Aplikace → auth → Instance musí existovat další instance:

Pole	Produkční hodnota
Hostname	api.auth.jabcore.cloud
Redirect URI	https://api.auth.jabcore.cloud/docs/auth/callback
Post logout redirect URI	https://api.auth.jabcore.cloud/docs/
Brand	Jabcore

Po přidání instance spusť synchronizaci aplikace auth se ZITADEL. API při startu loginu kontroluje přesnou dvojici oidcClientId + redirectUri; bez instance skončí bezpečně chybou a callback si nevymyslí.

Přístup coding AI

Přihlášený člověk otevře položku AI přístup v horní navigaci dokumentace a vygeneruje token. Token:

• je podepsaný jiným HS256 secretem než ZITADEL JWT;
• má audience documentation-ai a jediný scope docs:read;
• platí 24 hodin;
• není ukládán v databázi ani vracen podruhé;
• je zaznamenán v audit logu pouze jako událost s expirací — nikdy ne vlastní hodnota;
• nelze použít na běžné /api/* endpointy.

AI posílá token výhradně v hlavičce, nikdy v URL:

Authorization: Bearer <docs-token>

Pro načtení celého kontextu slouží:

GET /docs/llms-full.txt  # všechny Markdown zdroje v jednom souboru
GET /api/docs.json       # autoritativní OpenAPI schéma aktuálního buildu

Brána přijímá také X-Docs-Token, ale standardní Bearer hlavička je doporučená. Redirecty pro nepřihlášený browser se používají jen u HTML navigace; API klient dostane 401 DOCS_AUTH_REQUIRED.

Produkční konfigurace

Vygeneruj samostatný secret a nastav ho v produkčním .env:

openssl rand -base64 32

DOCS_TOKEN_SECRET=<výsledek předchozího příkazu>
DOCS_PUBLIC_BASE_URL=https://api.auth.jabcore.cloud

Při NODE_ENV=production je ochrana povinně aktivní a server s chybějícím nebo kratším než 32znakovým secretem nenastartuje. V lokálním developmentu je ochrana vypnutá, aby šel používat VitePress dev server bez produkčního OIDC callbacku.