NestJS Telegram WebApp Authentication Module

Модуль для авторизации через Telegram WebApp в приложениях NestJS.

Установка

npm install @andrei_filippov/nestjs-telegram-auth

Быстрый старт

1. Импорт модуля

import { Module } from '@nestjs/common';
import { TelegramAuthModule } from '@andrei_filippov/nestjs-telegram-auth';

@Module({
  imports: [
    TelegramAuthModule.forRoot({
      botToken: 'YOUR_BOT_TOKEN', // или используйте переменную окружения TELEGRAM_BOT_TOKEN
    }),
  ],
})
export class AppModule {}

2. Использование Guard

Применение к контроллеру

import { Controller, Get } from '@nestjs/common';
import { TelegramAuthGuard, CurrentTelegramUser, TelegramUser } from '@andrei_filippov/nestjs-telegram-auth';

@Controller('api')
@UseGuards(TelegramAuthGuard)
export class ApiController {
  @Get('profile')
  getProfile(@CurrentTelegramUser() user: TelegramUser) {
    return {
      message: `Привет, ${user.first_name}!`,
      user: user,
    };
  }
}

Применение к отдельному методу

import { Controller, Get, UseGuards } from '@nestjs/common';
import { TelegramAuthGuard, CurrentTelegramUser, TelegramUser } from '@andrei_filippov/nestjs-telegram-auth';

@Controller('api')
export class ApiController {
  @Get('public')
  getPublicData() {
    return { message: 'Публичные данные доступны всем' };
  }

  @Get('private')
  @UseGuards(TelegramAuthGuard)
  getPrivateData(@CurrentTelegramUser() user: TelegramUser) {
    return {
      message: `Приватные данные для ${user.first_name}`,
      userId: user.id,
    };
  }
}

API

TelegramAuthModule

forRoot(options)

Синхронная конфигурация модуля.

TelegramAuthModule.forRoot({
  botToken: 'YOUR_BOT_TOKEN',
})

forRootAsync(options)

Асинхронная конфигурация модуля.

TelegramAuthModule.forRootAsync({
  useFactory: (configService: ConfigService) => ({
    botToken: configService.get('TELEGRAM_BOT_TOKEN'),
  }),
  inject: [ConfigService],
})

TelegramAuthGuard

Guard для валидации данных Telegram WebApp. Проверяет:

• Наличие заголовка x-telegram-init-data
• Валидность подписи данных
• Время жизни данных (максимум 24 часа)

@CurrentTelegramUser()

Декоратор для получения данных пользователя Telegram.

Получение полного объекта пользователя

@Get('profile')
getProfile(@CurrentTelegramUser() user: TelegramUser) {
  return user;
}

Получение конкретного поля

@Get('user-id')
getUserId(@CurrentTelegramUser('id') userId: number) {
  return { userId };
}

@Get('username')
getUsername(@CurrentTelegramUser('username') username: string) {
  return { username };
}

Интерфейсы

TelegramUser

interface TelegramUser {
  id: number;
  first_name: string;
  last_name?: string;
  username?: string;
  language_code?: string;
  is_premium?: boolean;
  allows_write_to_pm?: boolean;
  photo_url?: string;
}

TelegramInitData

interface TelegramInitData {
  user: TelegramUser;
  chat_instance?: string;
  chat_type?: string;
  auth_date: number;
  signature?: string;
  hash: string;
}

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

Модуль автоматически использует переменную окружения TELEGRAM_BOT_TOKEN, если она установлена:

export TELEGRAM_BOT_TOKEN=your_bot_token_here

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

Полный пример контроллера

import { Controller, Get, Post, UseGuards, Body } from '@nestjs/common';
import { 
  TelegramAuthGuard, 
  CurrentTelegramUser, 
  TelegramUser 
} from '@andrei_filippov/nestjs-telegram-auth';

@Controller('telegram')
export class TelegramController {
  // Публичный эндпоинт
  @Get('info')
  getInfo() {
    return {
      message: 'Информация о Telegram WebApp',
      version: '1.0.0',
    };
  }

  // Защищенный эндпоинт
  @Get('profile')
  @UseGuards(TelegramAuthGuard)
  getProfile(@CurrentTelegramUser() user: TelegramUser) {
    return {
      id: user.id,
      name: `${user.first_name} ${user.last_name || ''}`.trim(),
      username: user.username,
      isPremium: user.is_premium,
      language: user.language_code,
    };
  }

  // Получение только ID пользователя
  @Get('user-id')
  @UseGuards(TelegramAuthGuard)
  getUserId(@CurrentTelegramUser('id') userId: number) {
    return { userId };
  }

  // Защищенный POST эндпоинт
  @Post('update-profile')
  @UseGuards(TelegramAuthGuard)
  updateProfile(
    @CurrentTelegramUser() user: TelegramUser,
    @Body() updateData: any,
  ) {
    return {
      message: `Профиль пользователя ${user.first_name} обновлен`,
      userId: user.id,
      updateData,
    };
  }
}

Конфигурация с ConfigService

import { Module } from '@nestjs/common';
import { ConfigModule, ConfigService } from '@nestjs/config';
import { TelegramAuthModule } from '@andrei_filippov/nestjs-telegram-auth';

@Module({
  imports: [
    ConfigModule.forRoot(),
    TelegramAuthModule.forRootAsync({
      useFactory: (configService: ConfigService) => ({
        botToken: configService.get<string>('TELEGRAM_BOT_TOKEN'),
      }),
      inject: [ConfigService],
    }),
  ],
})
export class AppModule {}

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

Guard выбрасывает следующие исключения:

• UnauthorizedException - если отсутствует заголовок x-telegram-init-data
• UnauthorizedException - если данные не прошли валидацию подписи
• UnauthorizedException - если данные устарели (старше 24 часов)
• BadRequestException - если формат данных неверный

import { Controller, Get, UseGuards, HttpException, HttpStatus } from '@nestjs/common';
import { TelegramAuthGuard, CurrentTelegramUser, TelegramUser } from '@andrei_filippov/nestjs-telegram-auth';

@Controller('api')
export class ApiController {
  @Get('protected')
  @UseGuards(TelegramAuthGuard)
  getProtectedData(@CurrentTelegramUser() user: TelegramUser) {
    if (!user) {
      throw new HttpException('Пользователь не найден', HttpStatus.NOT_FOUND);
    }
    
    return { data: 'Защищенные данные', user };
  }
}

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

• Все данные проверяются с использованием HMAC-SHA256 подписи
• Время жизни данных ограничено 24 часами
• Токен бота должен храниться в безопасном месте (переменные окружения)
• Guard автоматически валидирует подпись согласно документации Telegram

Лицензия

MIT

Поддержка

Если у вас есть вопросы или предложения, создайте issue в репозитории проекта.