photoplaces/obsidian_data/Photoplaces_data/atomic-api-contract-refresh-cookie.md

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