# Jizdaro auth.md

Jak se k Jizdaru přihlašují lidé a jak se k němu smí připojit AI agent nebo aplikace jednající za uživatele. English summary below.

## Pro koho

- **Lidé**: zákazníci Jizdara (česká webová kniha jízd, https://app.jizdaro.cz).
- **AI agenti a aplikace** (například Claude, ChatGPT nebo vlastní agent), které jednají za přihlášeného uživatele přes MCP server `https://app.jizdaro.cz/mcp`.
- **Bez přihlášení** fungují veřejné nástroje a API se sazbami cestovních náhrad a výpočty (`https://app.jizdaro.cz/api/v1`, MCP nástroje `sazby_cestovnich_nahrad`, `vypocet_nahrady`, `pausal_nebo_nahrady`, A2A `https://app.jizdaro.cz/a2a`). Žádné osobní údaje se v nich nevrací.

## Jak se přihlašuje člověk

Heslo neexistuje. Na https://app.jizdaro.cz/login se uživatel přihlásí:

- **e-mailem**: jednorázový odkaz nebo 6místný kód (platí 15 minut a jen jednou),
- **přes Google** (od Googlu se bere jen ověřená e-mailová adresa),
- **přístupovým klíčem** (passkey: otisk prstu, Face ID nebo PIN zařízení).

## Jak se připojí agent (OAuth 2.1)

Agent používá autorizační kód s **PKCE (S256, povinné)**. Tokeny jsou krátkodobé (access token 1 hodina, refresh token 30 dní s rotací; opakované použití starého refresh tokenu přístup zruší).

1. **Dynamická registrace klienta** (RFC 7591): `POST https://app.jizdaro.cz/oauth/register` s `client_name` a `redirect_uris`. Vznikne veřejný klient bez tajemství.
2. **Autorizace**: uživatel se otevře `https://app.jizdaro.cz/oauth/authorize` (`response_type=code`, `client_id`, `redirect_uri`, `code_challenge`, `code_challenge_method=S256`, `scope`, `state`), přihlásí se a na obrazovce souhlasu klikne **Povolit** nebo **Zamítnout**. Bez jeho souhlasu se nevydá nic.
3. **Token**: `POST https://app.jizdaro.cz/oauth/token` (`authorization_code` s `code_verifier`, nebo `refresh_token`).
4. **Volání MCP**: `Authorization: Bearer <access token>`. Bez tokenu odpoví chráněný nástroj `401` s hlavičkou `WWW-Authenticate: Bearer resource_metadata="…"`.

### Rozsahy (scopes)

| Rozsah | Co dovoluje |
|---|---|
| `jizdy:cteni` | číst vozidla, jízdy a měsíční souhrny |
| `jizdy:zapis` | zapisovat nové jízdy (stejná pravidla a limity tarifu jako v aplikaci); nic nemaže ani neupravuje |

### Přístup agenta přes ověřený e-mail (agent_auth)

Agent bez prohlížeče může požádat o přístup e-mailem uživatele:

1. Agent zaregistruje klienta (viz výše) a pošle `POST https://app.jizdaro.cz/oauth/agent/register` s `email`, `client_id`, `scope`, `code_challenge`, `code_challenge_method=S256`. Odpověď je vždy `202` s `request_id` (stejná, ať účet existuje, nebo ne).
2. Má-li e-mail v Jizdaru účet, uživatel dostane běžný e-mail s odkazem na schválení, přihlásí se a klikne Povolit nebo Zamítnout. Nic se neposílá, nezakládá ani nevydává bez jeho souhlasu.
3. Agent se ptá na `token_endpoint` s `grant_type=urn:jizdaro:params:oauth:grant-type:agent-request`, `client_id`, `request_id` a `code_verifier`. Do schválení dostává `authorization_pending`, po schválení tokeny, po zamítnutí `access_denied`. Žádost platí 15 minut.

## Kde jsou metadata

- Metadata autorizačního serveru (RFC 8414): https://jizdaro.cz/.well-known/oauth-authorization-server (issuer `https://jizdaro.cz`, koncové body na `https://app.jizdaro.cz`; obsahuje blok `agent_auth`).
- Metadata chráněného zdroje (RFC 9728): https://jizdaro.cz/.well-known/oauth-protected-resource (resource `https://jizdaro.cz`), https://app.jizdaro.cz/.well-known/oauth-protected-resource (resource `https://app.jizdaro.cz`) a https://app.jizdaro.cz/.well-known/oauth-protected-resource/mcp (resource `https://app.jizdaro.cz/mcp`, na ni odkazuje `WWW-Authenticate` z `/mcp`). Tokeny platí jen pro MCP server `https://app.jizdaro.cz/mcp`.
- MCP Server Card: https://jizdaro.cz/.well-known/mcp/server-card.json
- API katalog (RFC 9727): https://jizdaro.cz/.well-known/api-catalog
- Dokumentace: https://jizdaro.cz/pro-vyvojare/

## Jak se odebírá přístup

- Uživatel: v Jizdaru **Účet → Připojené aplikace** (odebere se celý přístup i všechny tokeny).
- Aplikace: `POST https://app.jizdaro.cz/oauth/revoke` s `token` (RFC 7009).
- Zrušení účtu smaže všechny přístupy.

Kontakt: podpora@jizdaro.cz

---

## English summary

Jizdaro (Czech trip log for sole proprietors and small businesses) has no passwords: people sign in with an e-mail link or code, Google, or a passkey at https://app.jizdaro.cz/login.

AI agents acting for a user connect to the MCP server `https://app.jizdaro.cz/mcp` using OAuth 2.1 with mandatory PKCE (S256) and dynamic client registration (RFC 7591). The user approves on a consent screen; scopes are `jizdy:cteni` (read trips) and `jizdy:zapis` (add new trips; nothing is deleted or edited). Access tokens last one hour; refresh tokens rotate. Agents without a browser can use the verified-email method (`agent_auth` in the authorization server metadata): the agent sends the user's e-mail, the user receives Jizdaro's regular sign-in e-mail and approves, and nothing is issued without that approval. Metadata: https://jizdaro.cz/.well-known/oauth-authorization-server and https://jizdaro.cz/.well-known/oauth-protected-resource. Users revoke access under Account → Connected apps (Účet → Připojené aplikace) or via `POST /oauth/revoke`.

Public rate and calculation tools (REST API, MCP tools, A2A) work without sign-in and return no personal data.
