# API контракт не соответствует реализации refresh token

**Контекст**: `backend/docs/API_CONTRACT.md` описывает передачу refresh token через заголовок `X-Refresh-Token`, но реальная реализация использует httpOnly cookie.

## Факт

- **Документация**: `- Refresh Token: ... передаётся в заголовке X-Refresh-Token` + `### POST /auth/refresh` → `- Заголовок: X-Refresh-Token: <refresh_token>`
- **Код**: `backend/internal/handlers/helpers.go:14-24` — `setRefreshTokenCookie()` устанавливает httpOnly cookie с именем `refresh_token`
- **Фронтенд**: `frontend/src/lib/api.ts:29` — `credentials: 'include'` для автоматической отправки cookie

## Исправление

API_CONTRACT.md обновлён:
- "передаётся в заголовке X-Refresh-Token" → "передаётся в httpOnly cookie `refresh_token`"
- Описание POST /auth/refresh: "Cookie: refresh_token (httpOnly, устанавливается при login/register/refresh)"

## Почему cookie, а не header

1. **Безопасность**: httpOnly cookie недоступен JavaScript'у — XSS-атака не украдёт refresh token
2. **Простота**: фронтенду не нужно хранить и явно отправлять refresh token — браузер делает это автоматически
3. **Refresh token rotation**: при каждом refresh старый токен удаляется из БД (с проверкой reuse)
4. **Cookie можно очистить через logout** на серверной стороне (MaxAge=-1)

## Связанные заметки

- [[atomic-frontend-types-backend-sync]] — другие разрывы контракта
- [[MOC-backend-patterns]]

## Теги

#api-docs #security #cookie #httpOnly #refresh-token