Какие есть подходы к передаче токена при скачивании файлов?

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

1. Заголовок Authorization (Наиболее рекомендуемый)

Токен передаётся в HTTP-заголовке, обычно в формате Bearer <token>. Это стандартный способ для REST API и многих клиентских библиотек (например, fetch, axios).

• Плюсы: Безопасен (токен не виден в URL, который может сохраниться в истории браузера или логах сервера). Чисто отделяет метаданные авторизации от данных запроса.
• Минусы: Не всегда применим для простых скачиваний по прямой ссылке в браузере (например, через тег <a>), так как браузер не добавляет этот заголовок автоматически.

// Пример запроса с использованием fetch API
fetch('https://api.example.com/files/123', {
  headers: {
    'Authorization': 'Bearer eyJhbGciOiJ...'
  }
})
.then(response => response.blob())
.then(blob => {
  // Обработка скачанного файла
});

2. Параметр URL (Query Parameter)

Токен добавляется к URL файла в виде query-параметра, например: /download/file.pdf?token=abc123.

• Плюсы: Очень просто реализовать. Работает для любых прямых ссылок, которые можно вставить в браузер, отправить по почте или использовать в теге <a href>.
• Минусы: Менее безопасен. Токен может быть сохранён в истории браузера, логах веб-сервера, реферерах. Не рекомендуется для долгоживущих или высокоуровневых токенов.

// Генерация ссылки для скачивания на стороне сервера (Node.js пример)
const downloadUrl = `https://api.example.com/download/${fileId}?access_token=${userToken}`;
// Эта ссылка может быть отправлена пользователю или использована во фронтенде.

3. Cookie

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

• Плюсы: Удобен для браузерных приложений (SPA), не требует ручной передачи токена в каждом запросе. Автоматически работает с тегом <a> и window.open.
• Минусы: Требует осторожной настройки (флаги HttpOnly, Secure, SameSite) для защиты от XSS и CSRF атак. Менее подходит для API, используемых не браузерами (мобильные приложения, серверные интеграции).

// Сервер (Express.js) устанавливает cookie при логине
res.cookie('access_token', token, {
  httpOnly: true, // Защита от XSS
  secure: true,   // Только по HTTPS
  sameSite: 'strict'
});
// При последующем запросе на /download/file.pdf браузер автоматически отправит cookie.

4. Комбинированные и специальные подходы

Иногда используются гибридные методы. Например, для одноразовых скачиваний генерируется временный signed URL с токеном в параметре, который самоуничтожается после использования. Также в некоторых API (например, AWS S3) используются предварительно подписанные URL (Pre-signed URLs), которые являются особым случаем передачи учётных данных через query-параметры.

Вывод: Для REST API и программируемых клиентов предпочтительнее использовать заголовок Authorization из соображений безопасности и чистоты API. Для сценариев, где пользователь должен скачать файл по прямой ссылке в браузере (например, по email), можно использовать временные токены в параметрах URL или организовать скачивание через промежуточный endpoint, который, проверив заголовок, перенаправит на фактический файл. Cookie — хороший выбор для традиционных веб-приложений, где фронтенд и бэкенд тесно связаны.