README

Telegram Auth 🔑

Features

• ✅ Telegram Login Widget – validate payloads from the login widget (hash verification, timestamp check).
• ✅ Telegram Web App – authenticate users inside mini‑apps by verifying initData.
• ✅ Third‑Party Use – validate Telegram data for external services (without a bot token, using bot ID).
• ✅ Simple API – ready‑to‑use methods like isValidLoginWidget(), validateWebApp(), plus exceptions for error handling.
• ✅ Secure by design – uses cryptographically strong hashing (hash_hmac, sodium) to prevent data tampering.
• ✅ PHP 8.2+ – modern, strictly typed code.

Requirements

• PHP: ^8.2
• ext-hash: *
• ext-sodium: *

Installation

composer require kilogram/auth

Quick start

Note

Usage examples are also available in the examples directory.

Login Widget (simple)

Basic validation of the data received from the Telegram Login Widget. Checks the hash and timestamp, returns a boolean result.

use Kilogram\Auth\Validator;

$data = $_GET;

$validator = new Validator($_ENV['TELEGRAM_BOT_TOKEN']);

if ($validator->isValidLoginWidget($data)) {
    echo "Authenticated. User ID: " . $data['id'];
} else {
    echo "Authentication failed";
}

Login Widget (with exceptions)

A more robust approach that throws specific exceptions for invalid input (missing parameters) and validation failures (tampered data).

use Kilogram\Auth\Validator;
use Kilogram\Auth\Exceptions\InvalidDataException;
use Kilogram\Auth\Exceptions\ValidationException;

$data = $_GET;

$validator = new Validator($_ENV['TELEGRAM_BOT_TOKEN']);

try {
    $validator->validateLoginWidget($data);
    echo "Authenticated. Hello " . ($data['first_name'] ?? 'user');
} catch (InvalidDataException $e) {
    // Developer error: invalid input format (e.g. missing "hash")
    echo "Bad request: " . $e->getMessage();
} catch (ValidationException $e) {
    // Invalid signature: possible tampering
    echo "Authentication failed";
}

Web App (simple)

Verifies the initData string from a Telegram Web App. Returns true if the signature is valid and the data is fresh.

use Kilogram\Auth\Validator;

$initData = $_POST['initData'];

$validator = new Validator($_ENV['TELEGRAM_BOT_TOKEN']);

if ($validator->isValidWebApp($initData)) {
    echo "Web App authenticated";
} else {
    echo "Invalid initData";
}

Web App (with exceptions)

Same as above, but throws exceptions for malformed input or invalid signatures, giving you finer control over error handling.

use Kilogram\Auth\Validator;
use Kilogram\Auth\Exceptions\InvalidDataException;
use Kilogram\Auth\Exceptions\ValidationException;

$initData = $_POST['initData'];

$validator = new Validator($_ENV['TELEGRAM_BOT_TOKEN']);

try {
    $validator->validateWebApp($initData);
    echo "Web App authenticated";
} catch (InvalidDataException $e) {
    // Developer error: initData format is broken / empty
    echo "Bad request: " . $e->getMessage();
} catch (ValidationException $e) {
    // Invalid signature
    echo "Authentication failed";
}

Web App Third-Party (simple)

Validates data for third‑party services without using a bot token. Only the bot ID is required.

use Kilogram\Auth\Validator;

$initData = $_POST['initData'];

if (Validator::isValidWebAppDataForThirdParty($initData, $botId)) {
    echo "Web App authenticated (Third-Party)!";
} else {
    echo "Invalid data";
}

Web App Third-Party (with exceptions)

The same third‑party validation, but with exception-based error reporting.

use Kilogram\Auth\Validator;
use Kilogram\Auth\Exceptions\ValidationException;

$initData = $_POST['initData'];

try {
    Validator::validateWebAppDataForThirdParty($initData, $botId);
    echo "Web App authorized!";
} catch (ValidationException $e) {
    echo "Authentication failed";
}

Tip

When to use simple vs exceptions?
Use the simple methods (isValid*) when you only need a boolean result (e.g., in controllers, middleware, or conditional logic).
Use the exception methods (validate*) when you need granular error handling – they distinguish between malformed input (developer errors, e.g., missing parameters) and invalid signatures (security issues, e.g., tampered data).

License

MIT