@actdim/app-telegram
v1.14.1
Published
Telegram OAuth bridge, account binding, direct Bot API notifier, and bot runtime for actdim apps
Maintainers
Readme
@actdim/app-telegram
Telegram OAuth bridge, account binding, direct Bot API notifier, and bot runtime for actdim applications.
Subpaths and Peer Dependencies
| Subpath | Description | Required Peers |
|---|---|---|
| . / ./contracts | DTOs, schemas, error codes, button models | @sinclair/typebox |
| ./init-data | Telegram Mini App initData HMAC validator | None (node:crypto) |
| ./db | Database table types and schema interface | kysely |
| ./migrations | Migration directory and source | None (node:url) |
| ./server | OAuth bridge, binding service, routes, notifier, modules | fastify, kysely, fast-jwt, get-jwks, @actdim/server-core, @actdim/core-contracts |
| ./bot | Bot router, Telegram adapter, commands, client | grammy, fastify |
| ./i18n/* | Error translation bundles (en, ru) | None |
Installation
pnpm add @actdim/app-telegramInstall the optional peer dependencies required by the subpaths your application consumes.
Environment Variables
Server Variables
| Variable | Subpath | Default | Description |
|---|---|---|---|
| TELEGRAM_OIDC_CLIENT_ID | ./server | "" | Telegram OAuth Client ID configured in Zitadel Generic OAuth IdP |
| TELEGRAM_BOT_TOKEN | ./server, ./bot | "" | Telegram Bot token from @BotFather |
| TELEGRAM_BOT_USERNAME | ./server, ./bot | "" | Bot username without @ for deep links (https://t.me/<bot>?start=bind_<ticket>) |
| TELEGRAM_BOT_SERVICE_SUBJECTS | ./server | "" | Comma-separated list of Zitadel machine user sub values authorized for /telegram/bot/* |
| WEBAPP_PUBLIC_URL | ./server, ./bot | "" | Public origin of the web application for connect links and buttons |
| TELEGRAM_BINDING_TICKET_TTL_SEC | ./server | 300 | Expiration time for one-time binding tickets in seconds |
| TELEGRAM_INIT_DATA_MAX_AGE_SEC | ./server | 86400 | Maximum age in seconds for valid Telegram Mini App initData |
| ZITADEL_API_URL | ./server | Auth authority | Zitadel API URL for user IdP link lookup |
| ZITADEL_MANAGEMENT_PAT | ./server | "" | Personal Access Token of Zitadel machine user with user read access |
| TELEGRAM_IDP_ID | ./server | "" | Zitadel Identity Provider ID for the Telegram IdP |
| TELEGRAM_API_ROOT | ./server, ./bot | https://api.telegram.org | Telegram Bot API base URL |
Bot Runtime Variables
| Variable | Default | Description |
|---|---|---|
| TELEGRAM_MODE | polling | Bot run mode (polling or webhook) |
| TELEGRAM_WEBHOOK_URL | "" | Public webhook URL registered with Telegram in webhook mode |
| TELEGRAM_WEBHOOK_PATH | /telegram/webhook | HTTP path where Fastify receives Telegram webhook updates |
| TELEGRAM_WEBHOOK_SECRET | "" | Secret token verified on incoming webhook payloads |
| TELEGRAM_WEBAPP_URL | "" | Optional Telegram Mini App URL for the primary button on /start |
| TELEGRAM_LOCAL_FILES_PATH | "" (dev) / /var/lib/telegram-bot-api (prod) | Mount path for local bot API file storage |
| <PREFIX>_API_URL | http://localhost:3000 (dev) / http://server:3000 (prod) | Backend server base URL |
| <PREFIX>_AUTH_AUTHORITY | "" | Zitadel authority URL |
| <PREFIX>_BOT_CLIENT_ID | "" | Machine user OAuth Client ID for /telegram/bot/* |
| <PREFIX>_BOT_CLIENT_SECRET | "" | Machine user OAuth Client Secret |
Zitadel Generic OAuth IdP Setup
Telegram provides an official OIDC provider, but Zitadel cannot consume it as Generic OIDC directly: Zitadel's OIDC library rejects Telegram's entire JWKS because one key uses ES256K (secp256k1, unsupported by go-jose).
To work around this, configure Telegram as a Generic OAuth IdP in Zitadel pointing to the bridge routes exposed by @actdim/app-telegram/server:
- Token Endpoint:
https://<server-domain>/auth/telegram/token - User Endpoint:
https://<server-domain>/auth/telegram/userinfo - ID Attribute: Set to
id(numeric Telegram user ID) to allow automatic account binding from IdP links.
The bridge forwards authorization code exchanges to Telegram and swaps the returned id_token into the access_token, allowing the userinfo endpoint to verify claims against Telegram's JWKS while skipping unsupported key curves.
Server Composition Example
import {
loadTelegramServerConfig,
createTelegramModule,
telegramAuthBridgeRoutes,
} from '@actdim/app-telegram/server';
import { createAuthModule } from '@actdim/server-core/auth';
const telegramConfig = loadTelegramServerConfig(process.env, {
authority: 'https://zitadel.example.com',
});
// Register auth module with telegram auth bridge routes:
const authModule = createAuthModule({
...authOptions,
afterRoutes: telegramAuthBridgeRoutes(telegramConfig.oauth),
});
// Register telegram binding module:
const telegramModule = createTelegramModule({
getDb: () => db,
config: telegramConfig.binding,
});Bot Composition Example
import {
loadBotConfig,
createCommandRouter,
createAccountCommands,
createStartCommand,
createClientCredentialsTokenProvider,
createBotBindingApi,
createBindingAccountService,
createTelegramBotService,
} from '@actdim/app-telegram/bot';
const config = loadBotConfig(process.env, { envPrefix: 'APP' });
// Setup account binding client to backend server
const tokens = createClientCredentialsTokenProvider(config.serverAuth);
const bindingApi = createBotBindingApi({ baseUrl: config.serverApiUrl, tokens });
const accountService = createBindingAccountService({ api: bindingApi });
// Account commands and start command
const account = createAccountCommands({ appName: 'MyPortal' });
const start = createStartCommand({
appName: 'MyPortal',
account,
});
// Command router
const router = createCommandRouter({
commands: [
start,
account.connectCommand,
account.accountCommand,
account.unbindCommand,
account.bindCallbackCommand,
],
});
// Run bot with health server (polling in dev, webhook in prod)
const botService = createTelegramBotService(
config,
router,
{ account: accountService },
{ serviceName: 'myportal-bot', account }
);
await botService.start();Architecture & Boundary Invariants
./contractsand./init-datahave zero server or bot framework dependencies../servernever importsgrammyor bot runtime internals../botnever importskysely, database tables, or server-core internals.- Notifier calls the Telegram Bot API directly via HTTPS using
TELEGRAM_BOT_TOKEN, independent of the bot process.
