# Telegram Webhook Validation

## Обзор

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

## Поддерживаемые возможности

### Команды бота:
- `/start` - приветствие и инструкции
- `/auth <token>` - авторизация пользователя
- `/status` - просмотр статуса последних ссылок

### Типы событий:
- `message` - текстовые сообщения (команды и ссылки)
- `edited_message` - отредактированные сообщения

## Архитектура валидации

### 1. TelegramWebhookValidator (Middleware)
Первичная проверка на уровне HTTP:

- **HTTP метод**: только POST
- **Content-Type**: application/json
- **update_id**: обязательное положительное число
- **Типы событий**: только `message` и `edited_message`
- **Размер payload**: максимум 1MB
- **User-Agent**: должен содержать "telegram"

### 2. TelegramWebhookRequest (FormRequest)
Детальная валидация структуры данных:

- Валидация полей `message` и `edited_message`
- Проверка обязательных полей (chat.id, from.id, text)
- Валидация типов данных и ограничений
- Приведение ID к целым числам

## Middleware Pipeline

```php
Route::post('/telegram/webhook', [TelegramWebhookController::class, 'handle'])
    ->middleware([
        'telegram.webhook-validator',  // Базовая валидация
        'telegram.replay-protection',  // Защита от replay атак
        'telegram.ip-whitelist',       // IP whitelist (если настроен)
        'telegram.rate-limit',         // Rate limiting
        'telegram.secret',             // Проверка секретного токена
    ]);
```

## Обработка ошибок

### HTTP статусы:
- `405 Method Not Allowed` - неверный HTTP метод
- `415 Unsupported Media Type` - неверный Content-Type
- `400 Bad Request` - неверный update_id или отсутствие событий
- `413 Payload Too Large` - превышен размер payload
- `403 Forbidden` - неверный User-Agent

### Логирование:
Все ошибки валидации логируются с контекстом:
- IP адрес источника
- Тип ошибки
- Детали запроса

## Конфигурация

### Environment Variables:
```env
TELEGRAM_SECRET_TOKEN=your_secret_token
TELEGRAM_RATE_LIMIT=60,1
TELEGRAM_ALLOWED_IPS=149.154.160.0/20,91.108.4.0/22
TELEGRAM_REPLAY_PROTECTION=true
```

### config/telegram.php:
```php
return [
    'secret_token' => env('TELEGRAM_SECRET_TOKEN'),
    'rate_limit' => [
        'max_attempts' => env('TELEGRAM_RATE_LIMIT_MAX', 60),
        'decay_minutes' => env('TELEGRAM_RATE_LIMIT_DECAY', 1),
    ],
    'allowed_ips' => env('TELEGRAM_ALLOWED_IPS') ? explode(',', env('TELEGRAM_ALLOWED_IPS')) : null,
    'replay_protection' => env('TELEGRAM_REPLAY_PROTECTION', true),
];
```

## Безопасность

### Рекомендации:
1. **Обязательно** настройте `TELEGRAM_SECRET_TOKEN`
2. **Рекомендуется** настроить IP whitelist для Telegram
3. **Рекомендуется** включить replay protection
4. **Настройте** rate limiting для предотвращения спама

### Telegram IP диапазоны:
- `149.154.160.0/20`
- `91.108.4.0/22`

## Примеры использования

### Успешный webhook:
```json
{
    "update_id": 123456789,
    "message": {
        "message_id": 1,
        "date": 1640995200,
        "chat": {
            "id": 123456789,
            "type": "private"
        },
        "from": {
            "id": 123456789,
            "first_name": "User",
            "is_bot": false
        },
        "text": "https://example.com"
    }
}
```

### Команда авторизации:
```json
{
    "update_id": 123456790,
    "message": {
        "message_id": 2,
        "date": 1640995201,
        "chat": {
            "id": 123456789,
            "type": "private"
        },
        "from": {
            "id": 123456789,
            "first_name": "User",
            "is_bot": false
        },
        "text": "/auth abc123token"
    }
}
```

## Мониторинг

### Логи для отслеживания:
- `telegram.webhook-validator` - ошибки валидации
- `telegram.rate-limit` - превышение лимитов
- `telegram.secret` - неверные токены
- `telegram.ip-whitelist` - блокировка по IP

### Метрики:
- Количество успешных webhook'ов
- Количество ошибок валидации по типам
- Время обработки запросов
- Использование rate limiting