@digiforce-nc/plugin-auth-telegram

Plugin xác thực qua Telegram Login — hỗ trợ hai luồng: Login Widget (cho web) và Web App (cho Telegram Mini Apps). Sử dụng HMAC-SHA256 để verify dữ liệu từ Telegram, đảm bảo tính toàn vẹn.

Plugin này làm gì?

TelegramAuth kế thừa BaseAuth, triển khai xác thực qua Telegram Bot API. Plugin hỗ trợ hai cơ chế verify khác nhau: Login Widget dùng HMAC với bot token hash, Web App dùng HMAC với WebAppData key. Cả hai đều không yêu cầu OAuth redirect truyền thống.

Hai luồng xác thực

#	Luồng	Khi nào dùng	Verify method
1	Login Widget	Web browser — nút Telegram Login	HMAC-SHA256 với SHA256(bot_token)
2	Web App	Telegram Mini App (WebApp)	HMAC-SHA256 với HMAC("WebAppData", bot_token)

Luồng xác thực — Web App

Cấu hình

Tham số	Kiểu	Mô tả
`telegram.botToken`	`string`	Bot Token từ @BotFather (server-side, không public)
`public.botUsername`	`string`	Username của bot (không có @, dùng cho Login Widget)
`telegram.http`	`boolean`	Dùng HTTP thay HTTPS cho redirect
`telegram.port`	`string`	Port tùy chỉnh cho redirect URL
`public.autoSignup`	`boolean`	Tự tạo tài khoản nếu user chưa tồn tại

HMAC Verification

Login Widget — verify theo Telegram Login Widget docs:

data_check_string = "auth_date=...\nfirst_name=...\nid=...\nusername=..."
secret_key = SHA256(bot_token)
hash = HMAC_SHA256(secret_key, data_check_string)

Web App — verify theo Telegram Web App docs:

data_check_string = "auth_date=...\nquery_id=...\nuser=..."
secret_key = HMAC_SHA256("WebAppData", bot_token)
hash = HMAC_SHA256(secret_key, data_check_string)

API endpoints

Endpoint	Quyền	Mô tả
`telegram:redirect`	Public (CORS)	Login Widget callback — verify HMAC và tạo session
`telegram:validate`	Public (CORS)	Web App validation — verify initData và tạo session

Cả hai endpoint đều bật CORS để hỗ trợ cross-origin requests từ Telegram Widget và Mini App.

Thành phần client

Thành phần	Mô tả
`TelegramLoginButton`	Widget đăng nhập Telegram (dùng package `telegram-login-button`)
`Options`	Form cấu hình Telegram auth trong Settings → Authentication

Dependencies

Package	Vai trò
`telegram-login-button`	React component cho Telegram Login Widget
`@digiforce-nc/auth`	Base auth framework (peer)
`@digiforce-nc/server`	Server framework (peer)
`@digiforce-nc/client`	Client framework (peer)