@sotuvcore/auth-telegram (0.2.0)

Published 2026-07-27 18:00:33 +05:00 by pulat

Setup this registry in your project .npmrc file:

@sotuvcore:registry=

To install the package using npm, run the following command:

npm install @sotuvcore/auth-telegram@0.2.0

or add it to the package.json file:

"@sotuvcore/auth-telegram": "0.2.0"

For more information on the npm registry, see the documentation.

@sotuvcore/auth-telegram

Telegram MiniApp auth provider для Sotuza (Medusa v2). HMAC-верификация initData от Telegram WebApp + резолвинг customer.

Возможности

HMAC-SHA256 верификация initData по официальному алгоритму Telegram (WebAppData → botToken → data_check_string → hash)
Constant-time сравнение hash (защита от timing attacks)
Проверка возраста initData (по умолчанию 24h, настраивается)
Upsert customer по telegram_id (первый вход = регистрация, следующие = login с обновлением метаданных)
13 unit-тестов (parse, hash compute, tamper detect, expiry, edge cases)

Установка

pnpm add @sotuvcore/auth-telegram

Подключение

В medusa-config.ts:

{
  resolve: '@medusajs/medusa/auth',
  options: {
    providers: [
      {
        resolve: '@medusajs/medusa/auth-emailpass',
        id: 'emailpass',
      },
      {
        resolve: '@sotuvcore/auth-telegram',
        id: 'telegram',
        options: {
          botToken: process.env.TELEGRAM_BOT_TOKEN!,
          maxAuthAgeSeconds: 86400, // 24h
        },
      },
    ],
  },
},

Flow

Клиент (MiniApp) читает window.Telegram.WebApp.initData (query string от Telegram)

POST /auth/customer/telegram:

{ "init_data": "auth_date=...&user=...&hash=..." }

Provider:
- Парсит query string
- Собирает data_check_string (все kv кроме hash, отсортированные, join \n)
- Вычисляет HMAC_SHA256(data_check_string, HMAC_SHA256(botToken, "WebAppData"))
- Constant-time сравнивает с полученным hash
- Проверяет auth_date (не старше maxAuthAgeSeconds)
- Ищет auth_identity с entity_id = "telegram:<user.id>"
- Если нет — создаёт, если есть — обновляет user_metadata
Medusa выдаёт JWT для клиента

Требования от MiniApp

Клиент должен передавать init_data ровно как получил от Telegram — без модификаций, без URL-декодирования. Любое изменение → hash mismatch.

Использование в клиенте (Next.js)

import WebApp from '@twa-dev/sdk'

const initData = WebApp.initData // строка query
const res = await fetch(`${MEDUSA_URL}/auth/customer/telegram`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ init_data: initData }),
})
const { token } = await res.json()
// token — JWT для дальнейших запросов с header Authorization: Bearer

Тесты

pnpm test

13 кейсов: parse (5), buildDataCheckString (1), computeInitDataHash (2), verifyInitData (5) — happy path, wrong token, tamper, expired, skip expiry, missing hash.

Roadmap

v0.2 — привязка auth_identity к customer (customer creation в MiniApp через workflow)
v0.3 — refresh token flow (Telegram initData обновляется при каждом open)
v0.4 — bind existing customer (веб-клиент оффлайн → добавил Telegram)

Development dependencies

ID	Version
@medusajs/framework	^2.17.0
@medusajs/types	^2.17.0
typescript	^5.5.0
vitest	^2.0.0

Peer dependencies

ID	Version
@medusajs/framework	^2.17.0

Details

npm

2026-07-27 18:00:33 +05:00

UNLICENSED

latest

6.7 KiB

Assets (1)

auth-telegram-0.2.0.tgz 6.7 KiB

Versions (1) View all

0.2.0

2026-07-27