Миграция на BFF: авторизация и CSRF

Как BFF хранит сессию, обновляет токены и защищается от CSRF, а затем десять сценариев по шагам. Общая картина — «Обзор», формат ручек — «Контракт». Как защита устроена сейчас — в разделе CSRF.

BFF держит всю сессию в одной cookie __Host-Http-session. Токены Go API лежат внутри неё в зашифрованном виде, а в браузер не попадает ничего, что JavaScript мог бы прочитать.

Атрибут	Значение
Имя	`__Host-Http-session`
`HttpOnly`	да
`Secure`	да
`Path`	`/`
`SameSite`	`Strict`
`Domain`	не задаётся
`Max-Age`	`refresh_expires_in` из ответа Go

Значение — base64url(iv ‖ шифротекст ‖ тег): AES-256-GCM, ключ SESSION_KEY (32 байта), имя cookie служит AAD (дополнительные аутентифицируемые данные). iv — 12 случайных байт из CSPRNG (crypto.getRandomValues), новые при каждом шифровании; повтор IV с тем же SESSION_KEY ломает GCM. Ошибка расшифровки или тега — сессии нет, и процедуры с сессией отвечают UNAUTHORIZED. Внутри — JSON:

json

{ "access": "…", "refresh": "…", "accessExp": 1760000000, "refreshExp": 1762600000 }

Пример формы; значения токенов и ключа на страницах не приводятся.

Что говорит RFC 10017. Атрибуты и префикс (§6.1.3.2):

The BFF MUST enable the Secure flag for its cookies.

The BFF MUST enable the HttpOnly flag for its cookies.

The BFF SHOULD enable the SameSite=Strict flag for its cookies.

The BFF SHOULD start the name of its cookie with a prefix indicating the cookie was set via HTTP, for example, by using the __Host-Http- prefix defined in [COOKIES].

Шифрование там же:

the BFF SHOULD encrypt its cookie contents.

Сессия в самой cookie допустима (§6.1.2.3): раз cookie нужна только для получения токенов, управление и отзыв следуют из access и refresh.

It suffices to revoke the user's access token and/or refresh token to prevent ongoing access to protected resources, without the need to explicitly invalidate the cookie-based session.

Почему не Redis и не память процесса: BFF остаётся без состояния. Деплой на каждый коммит main никого не разлогинивает, новых сервисов не появляется. Цена: смена SESSION_KEY разлогинивает всех.

Как BFF обрабатывает вызов

Каждый вызов к /api/trpc — query, mutation или батч — проходит один путь, включая auth.login, auth.register и auth.logout:

createContext проверяет CSRF (раздел «CSRF» ниже). Не прошли — FORBIDDEN с appCode: csrf_invalid (HTTP 403): роутер не вызывается, в Go ничего не уходит.
createContext расшифровывает cookie __Host-Http-session в ctx.session; cookie нет или она не расшифровывается — null.
Все процедуры, кроме auth.*, построены на authedProcedure: без сессии — UNAUTHORIZED (HTTP 401). Несуществующая процедура — NOT_FOUND от tRPC (см. «Контракт»).
Если до accessExp меньше 30 с, authedProcedure обновляет токены через refresh до вызова Go.
Процедура вызывает Go через ctx.go (GO_API_URL, на одной VPS http://api:8080/api/v1) с Authorization: Bearer. На двух VPS к нему добавляется X-BFF-Key, см. «Две VPS».
403 s2s_forbidden от Go (ключ не принят) — инфраструктурная ошибка: BAD_GATEWAY (HTTP 502), запись в лог, refresh не делать, сессию не трогать.
Если Go ответил 401, обновить токены и повторить вызов один раз.
Ответить результатом процедуры; если токены сменились, BFF дописывает новую cookie в resHeaders. Остальные ошибки Go переводятся по таблице «Ошибки».

Исключение — auth.logout. Он построен на optionalSessionProcedure: если сессия есть, вызывает Go тем же клиентом ctx.go — с refresh до вызова и одним повтором после 401, чтобы refresh-токен отозвался и при истёкшем access; ошибки Go он не пробрасывает. auth.logout никогда не отвечает UNAUTHORIZED: после проверки CSRF он всегда успешен. Без cookie сессии Go не вызывается; cookie сессии и три старые cookie (access_token с Path=/api/v1, refresh_token с Path=/api/v1/auth, __Host-csrf с Path=/) стираются в любом случае.

В Go уходят только аргументы процедуры, собранные сгенерированным клиентом, и X-Request-ID; Cookie и X-CSRF не уходят. Authorization и (на двух VPS) X-BFF-Key ставит сам BFF, поэтому клиент не может подсунуть свой X-BFF-Key. Ответ Go в браузер не уходит, только результат процедуры: cookie выставляет только BFF.

Одновременные refresh объединяются. Ключ — SHA-256 refresh-токена, результат держится в памяти 10 с: вторая вкладка со старой cookie получает те же новые токены. Если Go отвергает refresh (401), BFF стирает cookie (Max-Age=0) и отвечает UNAUTHORIZED.

CSRF

Три правила, все на стороне BFF (исключение — upgrade WebSocket, см. ниже). Проверки идут первыми из проверок BFF, в createContext, раньше расшифровки cookie, и для каждого вызова, включая вход, регистрацию и выход:

Каждый вызов к /api/trpc без X-CSRF: 1 получает 403 csrf_invalid и в Go не уходит. Чужой origin не может поставить такой заголовок без preflight, а CORS BFF не разрешает никому: клиент живёт на том же origin.
Для POST (mutation и батч мутаций): Origin равен APP_ORIGIN, а Sec-Fetch-Site, если он есть, равен same-origin; иначе 403 csrf_invalid.
SameSite=Strict: cookie не уходит на межсайтовые запросы. SPA это не мешает: HTML отдаётся без cookie, а запросы к API делает страница того же сайта.

Ещё раньше tRPC сам разбирает запрос: тело не в JSON (application/x-www-form-urlencoded и text/plain — так шлёт обычная HTML-форма) он отклоняет 415 UNSUPPORTED_MEDIA_TYPE, не вызывая createContext. Форма с multipart/form-data доходит до проверок CSRF и получает 403.

Первое правило — прямой путь из RFC (§6.1.3.3.2):

When this mechanism is used, the BFF MUST ensure that every incoming request carries this static header.

Подписанный Double Submit, как в нынешней реализации, RFC не ставит выше (§6.1.3.3.3):

Note that this mechanism is not necessarily recommended over the CORS approach.

WebSocket (будущая потоковая отдача вывода рантайма) устроен иначе. Браузерный API не умеет ставить свои заголовки, так что X-CSRF: 1 на upgrade поставить нельзя: upgrade освобождён от X-CSRF и защищён проверкой Origin плюс SameSite=Strict. Нет Origin или он не равен APP_ORIGIN — 403. Причина в том, что у WebSocket нет CORS и preflight (Cross-Site WebSocket Hijacking): cookie SameSite=Strict не уйдёт на рукопожатие с чужого сайта, но уйдёт с поддомена того же сайта (сценарий), поэтому проверка Origin обязательна.

Фронту больше не нужно читать cookie, повторять запрос после 403 и обновлять токены на 401: 401 означает гостя и форму входа.

Сценарии

Участники: F — код фронта, B — браузер, P — BFF, A — Go API, E — чужой сайт.

Вход

Фронт шлёт логин с заголовком X-CSRF: 1. BFF проверяет заголовок и Origin, вызывает Go и получает токены в JSON. Токены остаются в BFF: браузеру уходят User и новая cookie, а три старые cookie стираются.