Securely Authenticate Users with the Telegram Login Widget in PHP and Yii2

<?php

namespace app\components;

use InvalidArgumentException;

class TelegramAuthValidator
{
    private string $botToken;

    public function __construct(string $botToken)
    {
        if (empty($botToken)) {
            throw new InvalidArgumentException("Telegram bot token cannot be empty.");
        }
        $this->botToken = $botToken;
    }

    /**
     * Validates the Telegram authentication payload.
     * 
     * @param array $params The query parameters received from Telegram.
     * @param int $maxAge Maximum allowed age of the authentication in seconds (default: 24 hours).
     * @return bool True if the payload is valid and fresh, false otherwise.
     */
    public function validate(array $params, int $maxAge = 86400): bool
    {
        if (!isset($params['hash']) || !isset($params['auth_date'])) {
            return false;
        }

        // Prevent replay attacks by checking the age of the authentication
        $authDate = (int)$params['auth_date'];
        if ((time() - $authDate) > $maxAge) {
            return false;
        }

        $receivedHash = $params['hash'];
        unset($params['hash']);

        // Sort parameters alphabetically by key
        ksort($params);

        // Build the data-check-string
        $dataCheckArr = [];
        foreach ($params as $key => $value) {
            $dataCheckArr[] = $key . '=' . $value;
        }
        $dataCheckString = implode("\n", $dataCheckArr);

        // Derive the secret key from the bot token
        $secretKey = hash('sha256', $this->botToken, true);

        // Calculate the HMAC-SHA-256 signature
        $calculatedHash = hash_hmac('sha256', $dataCheckString, $secretKey);

        // Compare hashes securely
        return hash_equals($calculatedHash, $receivedHash);
    }
}

# Create migration
./yii migrate/create add_telegram_id_to_user_table

<?php

use yii\db\Migration;

class m231024_120000_add_telegram_id_to_user_table extends Migration
{
    public function safeUp()
    {
        $this->addColumn('{{%user}}', 'telegram_id', $this->string(64)->unique()->null());
        $this->createIndex('idx-user-telegram_id', '{{%user}}', 'telegram_id', true);
    }

    public function safeDown()
    {
        $this->dropIndex('idx-user-telegram_id', '{{%user}}');
        $this->dropColumn('{{%user}}', 'telegram_id');
    }
}

<?php

namespace app\controllers;

use Yii;
\use yii\web\Controller;
\use yii\web\BadRequestHttpException;
\use yii\web\ServerErrorHttpException;
\use app\models\User;
\use app\components\TelegramAuthValidator;

class AuthController extends Controller
{
    /**
     * Handles the redirect callback from the Telegram Login Widget.
     */
    public function actionTelegramCallback()
    {
        $request = Yii::$app->request;
        $params = $request->get();

        // Retrieve the bot token securely from environment variables or application parameters
        $botToken = Yii::$app->params['telegram.bot_token'] ?? getenv('TELEGRAM_BOT_TOKEN');
        if (empty($botToken)) {
            throw new ServerErrorHttpException("Telegram bot configuration is missing.");
        }

        $validator = new TelegramAuthValidator($botToken);

        // Validate signature and enforce a 12-hour expiration window
        if (!$validator->validate($params, 43200)) {
            throw new BadRequestHttpException("Invalid or expired Telegram authentication payload.");
        }

        $telegramId = (string)$params['id'];

        // Attempt to find an existing user mapped to this Telegram ID
        $user = User::findOne(['telegram_id' => $telegramId]);

        if (!$user) {
            // If the user is already logged in, link their current account
            if (!Yii::$app->user->isGuest) {
                $user = Yii::$app->user->identity;
                $user->telegram_id = $telegramId;
                if (!$user->save(true, ['telegram_id'])) {
                    throw new ServerErrorHttpException("Failed to link Telegram account.");
                }
            } else {
                // Otherwise, register a new user account
                $user = new User();
                $user->telegram_id = $telegramId;
                $user->username = $params['username'] ?? 'tg_' . $telegramId;
                // Generate a random password and email placeholder if required by your schema
                $user->password_hash = Yii::$app->security->generatePasswordHash(random_bytes(32));

                if (!$user->save()) {
                    Yii::error("Failed to register Telegram user: " . json_encode($user->getErrors()), __METHOD__);
                    throw new ServerErrorHttpException("Failed to register user account.");
                }
            }
        }

        // Log the user in
        Yii::$app->user->login($user, 3600 * 24 * 30); // 30-day session

        return $this->goBack();
    }
}