nestjs-telegram-auth/README.md

NestJS guard for validating Telegram WebApp init data

# NestJS Telegram Auth

Модуль для [NestJS](https://nestjs.com/), позволяющий валидировать и парсить [Telegram WebApp Init Data](https://core.telegram.org/bots/webapps#initializing-mini-apps) из HTTP-заголовка `x-telegram-auth`.

## 🚀 Установка

```bash
npm install nestjs-telegram-auth
```

или

```bash
yarn add nestjs-telegram-auth
```

## 📦 Подключение

```ts
import { Module } from '@nestjs/common';
import { TelegramInitDataModule } from 'nestjs-telegram-auth';

@Module({
  imports: [
    TelegramInitDataModule.forRoot({
      botToken: process.env.TELEGRAM_BOT_TOKEN,
      nodeEnv: process.env.NODE_ENV,
    }),
  ],
})
export class AppModule {}
```

Если `botToken` и `nodeEnv` не заданы в `forRoot`, модуль автоматически возьмёт их из переменных окружения `TELEGRAM_BOT_TOKEN` и `NODE_ENV`.

---


## 🔐 Использование Guard

`TelegramInitDataGuard` проверяет корректность данных и прикрепляет объект `InitData` к `request.telegramInitData`.

**Production режим:**
1. Проверка подписи с помощью `botToken`.
2. Парсинг InitData.
3. Привязка InitData к `request.telegramInitData`.

**Development режим:**
1. Пропуск проверки подписи.
2. Парсинг InitData.
3. Привязка InitData к `request.telegramInitData`.

Пример:

```ts
import { Controller, Get, UseGuards, Req } from '@nestjs/common';
import { TelegramInitDataGuard } from 'nestjs-telegram-auth';

@Controller('profile')
export class ProfileController {
  @Get()
  @UseGuards(TelegramInitDataGuard)
  getProfile(@Req() req: any) {
    return req.telegramInitData;
  }
}
```

---


## 📜 Формат заголовка

`x-telegram-auth` должен содержать данные в формате query string:

```
x-telegram-auth: query_id=AA...&user=%7B%22id%22%3A123456%2C%22first_name%22%3A%22John%22%7D&auth_date=1680000000&hash=abcd...
```

---


## ⚙️ Переменные окружения

| Переменная            | Описание                                     |
|-----------------------|----------------------------------------------|
| `TELEGRAM_BOT_TOKEN`  | Токен Telegram-бота                          |
| `NODE_ENV`            | `production` или `development`              |

---


## 📚 API

### `TelegramInitDataModule.forRoot(options?: TelegramInitDataModuleOptions)`

**Параметры:**
- `botToken?: string` — токен Telegram-бота.
- `nodeEnv?: string` — окружение (`production` или `development`).

### `TelegramInitDataGuard`

Guard, валидирующий и парсящий `x-telegram-auth`, результат доступен в `request.telegramInitData`.

---


## 📄 Лицензия

MIT