Аутентификация

Перед тем как что-то менять

Страницы безопасности описывают границы, которые защищают общие системы и данные пользователей. Убедись, что понимаешь границу, которую собираешься изменить, прежде чем тестировать или модифицировать что-либо.

Crawbl поддерживает два пути аутентификации, и они взаимно исключают друг друга для каждого запроса.

Простыми словами, эта страница отвечает на два вопроса:

1. как запрос доказывает, кто является пользователем?
2. какой слой отклоняет запрос, если это доказательство неверно?

Понимание того, какой путь применяется и где происходит валидация, необходимо для отладки проблем с аутентификацией и добавления новых клиентов.

Два пути аутентификации

Click diagram to zoom

HMAC (мобильное приложение)

Это основной путь для Flutter-мобильного приложения. Клиент отправляет Firebase ID-токен в X-Token плюс HMAC-заголовки, привязанные к устройству, при каждом запросе.

Это можно понять как двухэтапную проверку:

• токен говорит, кто является пользователем
• HMAC-заголовки доказывают, что запрос пришёл от клиента, который знает общий секрет подписи

1

Step 1

Send the mobile headers

Приложение отправляет X-Token, X-Timestamp, X-Signature, X-Device-Info и X-Version.

2

Step 2

Validate the HMAC

На границе Envoy WASM-фильтр проверяет, что временная метка свежая и HMAC-подпись совпадает.

3

Step 3

Validate the Firebase token

SecurityPolicy Envoy валидирует Firebase JWT из того же заголовка X-Token.

4

Step 4

Forward trusted identity

Если обе проверки проходят, Envoy пересылает доверенные заголовки X-Firebase-* в оркестратор.

5

Step 5

Resolve the user

Оркестратор читает эти доверенные заголовки и ищет запись пользователя.

Когда использовать: мобильные клиенты и любой клиент, который может безопасно хранить Firebase-токен и вычислять HMAC-SHA256-подписи.

JWT (стандартные клиенты)

Этот путь использует стандартный Firebase ID-токен в заголовке Authorization.

Это более простой путь. Именно его должны использовать большинство бэкенд-инструментов, скриптов или немобильных клиентов.

1

Step 1

Send a bearer token

Клиент отправляет Authorization: Bearer <firebase-id-token>.

2

Step 2

Validate it at the edge

SecurityPolicy Envoy валидирует токен через JWKS-эндпоинт Firebase.

3

Step 3

Forward the decoded identity

Если токен действителен, Envoy пересылает доверенные заголовки X-Firebase-*.

4

Step 4

Attach the principal

Оркестратор читает эти заголовки и преобразует их в принципал запроса, используемый кодом бэкенда.

Когда использовать: веб-дашборды, межсервисные вызовы, CLI-инструменты и другие клиенты, которые уже используют стандартные Bearer-токены.

Взаимная исключительность

Один запрос использует один из путей, но не оба одновременно. WASM-фильтр проверяет наличие заголовка X-Token:

• Если X-Token присутствует, фильтр применяет валидацию HMAC, а JWT валидируется из X-Token
• Если X-Token отсутствует, запрос следует стандартному пути Authorization: Bearer

Это означает, что никакой неоднозначности в том, какой путь применяется, нет.

Где происходит валидация

Проверка	Где	Что происходит при ошибке
HMAC-подпись	WASM-фильтр Envoy (граница)	401/403 до достижения бэкенда
Firebase JWT в X-Token или Authorization	SecurityPolicy Envoy (граница)	401 до достижения бэкенда
Извлечение заголовков идентификации	Middleware оркестратора	401 от бэкенда

Ключевой момент: оба пути отклоняют невалидные запросы на границе. В продакшене оркестратор никогда не видит неаутентифицированный трафик. Middleware бэкенда только читает доверенные заголовки, пересланные Envoy.

Добавление нового клиента

Если ты создаёшь нового клиента, выбери путь аутентификации исходя из того, какие заголовки он может отправлять:

• Мобилеподобные клиенты, которые могут вычислять HMAC и отправлять X-Token, должны использовать путь HMAC
• Стандартные клиенты, которые уже используют Bearer-токены, должны использовать путь JWT

Оба пути приводят к одному и тому же middleware оркестратора, который прикрепляет Principal к контексту запроса. Дальше код работает одинаково, независимо от того, как пользователь аутентифицировался.

В будущем: поток интеграции OAuth

Когда появятся подключения к сторонним приложениям (Gmail, Slack, Calendar), OAuth будет работать так:

Click diagram to zoom

Ключевые проектные решения:

• Мобильный клиент использует flutter_appauth для OAuth-потока с PKCE
• Токены хранятся на стороне сервера; агенты не получают «сырые» учётные данные провайдера
• MCP-инструменты вызывают внешние API, используя сохранённые токены от имени пользователя
• Планируемые провайдеры: Slack, Gmail, Calendar, Jira, Asana, Notion, Zoom и GitHub

Что дальше

Валидация подписи устройства на границе обрабатывается выделенным фильтром авторизации, который работает на уровне ingress.