Skip to main content

Steam Trade Integration

Интеграция Steam торговых офферов для вывода скинов пользователями.

1. Summary​

Goal: Автоматическая отправка Steam трейд-офферов при выводе скинов пользователями.

User Value:

  • Пользователи могут вывести выигранные скины на свой Steam аккаунт
  • Автоматическая обработка — без ручного вмешательства администраторов
  • Защита от дублирования через idempotency checks

2. Business Logic​

Trade Flow​

1. Withdrawal Request

  • Пользователь выбирает скин из инвентаря
  • Указывает Steam Trade URL
  • Система проверяет наличие скина в боте

2. Trade Offer Creation

  • Бот создаёт трейд-оффер с выбранным скином
  • Сохраняет tradeOfferId в Withdrawal запись
  • Логирует операцию для аудита

3. Trade Confirmation

  • Бот автоматически подтверждает оффер через mobile authenticator
  • Steam отправляет уведомление пользователю
  • Пользователь принимает трейд в Steam клиенте

4. Status Tracking

  • Система отслеживает статус оффера
  • Обновляет Withdrawal.status при изменениях
  • Уведомляет пользователя о завершении
Idempotency Protection

Каждый withdrawal имеет уникальный ID. Повторные запросы для того же withdrawal не создают новый трейд-оффер.

Edge Cases​

СитуацияПоведениеКод
❌ Bot offlineError 503BOT_OFFLINE
❌ Invalid Trade URLError 400INVALID_TRADE_URL
❌ Item not in bot inventoryError 404ITEM_NOT_FOUND
⏱️ Trade offer expiredUpdate status to EXPIRED—
✅ Trade acceptedUpdate status to COMPLETED—

3. ADR (Architectural Decisions)​

Steam Library Choice​

Problem: Нужна библиотека для управления Steam трейдами.

Decision: Используем steam-tradeoffer-manager от DoctorMcKay.

Rationale:

  • ✅ Официальная библиотека от создателя Steam Node.js экосистемы
  • ✅ Активно поддерживается (последнее обновление: август 2025)
  • ✅ Широко используется в community
  • ✅ Полная документация и примеры

Alternatives (rejected):

  • Custom implementation — слишком сложно (Steam API недокументирован)
  • Другие библиотеки — unmaintained или incomplete

Security Vulnerabilities (Accepted Risk)​

Problem: Transitive dependencies содержат уязвимости через request@2.88.2.

Decision: Accept as calculated risk with mitigation controls.

See: ADR 004: Steam Trade Library Security

Mitigation:

  • Docker container isolation
  • No direct user input to trade manager
  • Weekly vulnerability monitoring

4. Architecture​

Services Overview​

Key Components​

КомпонентПутьОписание
SteamBotServicebackend/src/domains/steam-trade-bot/services/steam-bot.service.tsУправление Steam клиентом, логин, сессии
TradeManagerServicebackend/src/domains/steam-trade-bot/services/trade-manager.service.tsСоздание и управление трейд-офферами
TradeStatusTrackerServicebackend/src/domains/steam-trade-bot/services/trade-status-tracker.service.tsОтслеживание статуса офферов
BotInventoryCacheServicebackend/src/domains/steam-trade-bot/services/bot-inventory-cache.service.tsКэширование инвентаря бота
IncomingTradeServicebackend/src/domains/steam-trade-bot/services/incoming-trade.service.tsОбработка входящих трейдов

5. Database Schema​

Models​

МодельОписаниеКлючевые поля
WithdrawalИстория выводов скиновtradeOfferId, status, itemId

Withdrawal Status Flow​

6. API Endpoints​

Admin API​

МетодЭндпоинтОписаниеDocs
GET/admin/steam-trade/inventoryПолучить инвентарь бота—
GET/admin/steam-trade/statusСтатус бота (online/offline)—
POST/admin/steam-trade/refresh-inventoryОбновить кэш инвентаря—

User API​

МетодЭндпоинтОписаниеDocs
POST/api/withdrawalsСоздать запрос на вывод→
GET/api/withdrawals/:idСтатус вывода→

7. Configuration​

Environment Variables​

ПеременнаяОписаниеОбязательна
STEAM_BOT_USERNAMESteam логин бота✅
STEAM_BOT_PASSWORDSteam пароль✅
STEAM_BOT_SHARED_SECRETMobile authenticator secret✅
STEAM_BOT_IDENTITY_SECRETIdentity secret для подтверждений✅
STEAM_API_KEYSteam Web API ключ✅
Secrets Management

Все credentials хранятся в .env и НЕ КОММИТЯТСЯ в git. Production secrets управляются через Dokploy environment variables.

8. Known Vulnerabilities (Accepted Risk)​

Transitive Dependencies via request@2.88.2​

Vulnerabilities:

  • form-data - CRITICAL (RCE)
  • nth-check - HIGH (ReDoS)
  • lodash.pick - HIGH (Prototype pollution)

Status: ✅ Accepted as calculated risk

Mitigation:

  • Bot runs in isolated Docker container
  • No direct user input to trade manager
  • Monitored for security updates from DoctorMcKay
  • Weekly pnpm audit review
  • Re-evaluate if CRITICAL exploit published

Why not fixed:

  • All Steam libraries in ecosystem depend on request@2.88.2
  • Libraries are actively maintained (last update: August 2025)
  • No migration path exists until maintainer rewrites to remove request

Monitoring:

cd backend
pnpm audit | grep -E "CRITICAL|HIGH"

See: ADR 004: Steam Trade Library Security

9. Dependencies​

Core Libraries​

PackageVersionStatusAuthor
steam-tradeoffer-manager2.12.2✅ MaintainedDoctorMcKay
steamcommunity3.49.0✅ MaintainedDoctorMcKay
steam-user5.0.0✅ MaintainedDoctorMcKay
steam-totp2.1.2✅ MaintainedDoctorMcKay

Last verified: 2026-02-16

All libraries are actively maintained by the original creator (DoctorMcKay) and receive regular updates.