@emaxe/tuigram 1.0.1 → 1.1.0

package/.env.example

@@ -27,3 +27,20 @@ AUTO_SCROLL=true
 
 # Показывать уведомления о наборе текста (true/false)
 SHOW_TYPING=true
+
+# ── Proxy Settings ────────────────────────────────────────────────────────────
+# Поддерживаются HTTP и SOCKS5 (как с авторизацией, так и без).
+# Формат единого URL:
+# PROXY_URL=http://127.0.0.1:8080
+# PROXY_URL=http://user:password@proxy.example.com:8080
+# PROXY_URL=socks5://127.0.0.1:1080
+# PROXY_URL=socks5://user:password@127.0.0.1:1080
+#
+# Либо отдельными переменными:
+# PROXY_TYPE=http
+# PROXY_HOST=127.0.0.1
+# PROXY_PORT=8080
+# PROXY_USERNAME=
+# PROXY_PASSWORD=
+# PROXY_TIMEOUT=10
+

package/CHANGELOG.md

@@ -13,6 +13,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 - English localization of the TUI and CLI interface strings.
 
+## [1.1.0] — 2026-08-31
+
+### Added
+
+- Support for HTTP/HTTPS (via HTTP CONNECT) and SOCKS5/SOCKS4 proxies with optional username and password authentication.
+- Proxy configuration options via `.env` (`PROXY_URL` or `PROXY_TYPE`/`PROXY_HOST`/`PROXY_PORT`/`PROXY_USERNAME`/`PROXY_PASSWORD`) and standard environment variables (`HTTPS_PROXY`, `HTTP_PROXY`, `ALL_PROXY`).
+- Display of active proxy status with password masking in `tuigram paths`.
+
 ## [1.0.1] — 2026-08-29
 
 Documentation and packaging only — no runtime changes.
@@ -103,6 +111,7 @@ First public release.
 - A WCAG contrast test (3:1 threshold) applied to every theme **after** conversion
   to xterm-256 — the colors are checked exactly as the user sees them.
 
-[Unreleased]: https://github.com/emaxe/tuigram/compare/v1.0.1...HEAD
+[Unreleased]: https://github.com/emaxe/tuigram/compare/v1.1.0...HEAD
+[1.1.0]: https://github.com/emaxe/tuigram/compare/v1.0.1...v1.1.0
 [1.0.1]: https://github.com/emaxe/tuigram/compare/v1.0.0...v1.0.1
 [1.0.0]: https://github.com/emaxe/tuigram/releases/tag/v1.0.0

package/CHANGELOG.ru.md

@@ -13,6 +13,14 @@
 
 - Английская локализация строк интерфейса TUI и CLI.
 
+## [1.1.0] — 2026-08-31
+
+### Добавлено
+
+- Поддержка работы через HTTP/HTTPS (HTTP CONNECT) и SOCKS5/SOCKS4 прокси, как с авторизацией по логину и паролю, так и без неё.
+- Настройка прокси через `.env` (`PROXY_URL` или `PROXY_TYPE`/`PROXY_HOST`/`PROXY_PORT`/`PROXY_USERNAME`/`PROXY_PASSWORD`) и стандартные переменные окружения (`HTTPS_PROXY`, `HTTP_PROXY`, `ALL_PROXY`).
+- Отображение активного прокси с маскированием пароля в выводе команды `tuigram paths`.
+
 ## [1.0.1] — 2026-08-29
 
 Только документация и упаковка — поведение клиента не менялось.
@@ -105,6 +113,7 @@
 - Тест контраста по WCAG (порог 3:1) для каждой темы — **после** конверсии в xterm-256,
   то есть ровно в том виде, в каком цвет увидит пользователь.
 
-[Unreleased]: https://github.com/emaxe/tuigram/compare/v1.0.1...HEAD
+[Unreleased]: https://github.com/emaxe/tuigram/compare/v1.1.0...HEAD
+[1.1.0]: https://github.com/emaxe/tuigram/compare/v1.0.1...v1.1.0
 [1.0.1]: https://github.com/emaxe/tuigram/compare/v1.0.0...v1.0.1
 [1.0.0]: https://github.com/emaxe/tuigram/releases/tag/v1.0.0

package/README.md

@@ -55,6 +55,7 @@ TuiGram lets you use Telegram entirely from the terminal: browse your dialog lis
 - [Slash commands](#-slash-commands-in-the-input-box)
 - [Sending files and images](#-sending-files-and-images)
 - [Themes](#-themes)
+- [Proxy configuration](#-proxy-configuration)
 - [Command line usage (CLI)](#️-command-line-usage-cli)
 - [Project structure](#-project-structure)
 - [Security](#-security)
@@ -511,6 +512,35 @@ The contrast of every "text on background" pair is verified by an automated WCAG
 
 ---
 
+## 🌐 Proxy configuration
+
+TuiGram supports routing MTProto connections through HTTP (including HTTPS CONNECT) and SOCKS5/SOCKS4 proxies — both with and without username/password authentication.
+
+Proxy options can be configured in `.env` (or via environment variables):
+
+**Single URL:**
+```env
+PROXY_URL=http://127.0.0.1:8080
+PROXY_URL=http://user:password@proxy.example.com:8080
+PROXY_URL=socks5://127.0.0.1:1080
+PROXY_URL=socks5://user:password@127.0.0.1:1080
+```
+
+**Or separate variables:**
+```env
+PROXY_TYPE=http         # http, https, socks5, socks4
+PROXY_HOST=127.0.0.1
+PROXY_PORT=8080
+PROXY_USERNAME=user     # optional
+PROXY_PASSWORD=password # optional
+PROXY_TIMEOUT=10        # timeout in seconds (default: 10)
+```
+
+Standard environment variables `HTTPS_PROXY`, `HTTP_PROXY`, and `ALL_PROXY` are also supported as fallbacks.
+The active proxy status can be inspected using `tuigram paths`.
+
+---
+
 ## 🛠️ Command line usage (CLI)
 
 TuiGram can be used as a set of console utilities (when running from a repository
@@ -554,6 +584,7 @@ TuiGram/
 │   ├── state.js                 # Reactive centralized state store
 │   ├── telegram/
 │   │   ├── client.js            # MTProto client creation and management
+│   │   ├── socket.js            # MTProto network transport and proxy tunneling (HTTP/SOCKS5)
 │   │   ├── auth.js              # Interactive login wizard and 2FA
 │   │   ├── dialogs.js           # Fetching, filtering and searching dialogs
 │   │   ├── messages.js          # History loading, sending, editing, files, reactions

package/README.ru.md

@@ -51,6 +51,7 @@
 - [Слэш-команды](#-слэш-команды-в-поле-ввода)
 - [Отправка файлов и картинок](#-отправка-файлов-и-картинок)
 - [Темы оформления](#-темы-оформления)
+- [Прокси-сервер](#-прокси-сервер)
 - [Использование через консоль (CLI)](#️-использование-через-консоль-cli)
 - [Структура проекта](#-структура-проекта)
 - [Безопасность](#-безопасность)
@@ -505,6 +506,35 @@ TUI_THEME=light     # светлая
 
 ---
 
+## 🌐 Прокси-сервер
+
+TuiGram поддерживает маршрутизацию MTProto-соединений через HTTP (включая HTTPS CONNECT) и SOCKS5/SOCKS4 прокси — как с авторизацией по логину и паролю, так и без неё.
+
+Настройки прокси задаются в `.env` (или через переменные окружения):
+
+**Единый URL:**
+```env
+PROXY_URL=http://127.0.0.1:8080
+PROXY_URL=http://user:password@proxy.example.com:8080
+PROXY_URL=socks5://127.0.0.1:1080
+PROXY_URL=socks5://user:password@127.0.0.1:1080
+```
+
+**Либо отдельными переменными:**
+```env
+PROXY_TYPE=http         # http, https, socks5, socks4
+PROXY_HOST=127.0.0.1
+PROXY_PORT=8080
+PROXY_USERNAME=user     # опционально
+PROXY_PASSWORD=password # опционально
+PROXY_TIMEOUT=10        # таймаут в секундах (по умолчанию 10)
+```
+
+Также в качестве фолбэка поддерживаются стандартные переменные `HTTPS_PROXY`, `HTTP_PROXY` и `ALL_PROXY`.
+Проверить активное состояние прокси можно командой `tuigram paths`.
+
+---
+
 ## 🛠️ Использование через консоль (CLI)
 
 TuiGram можно запускать в режиме консольных утилит (при запуске из клона
@@ -548,6 +578,7 @@ TuiGram/
 │   ├── state.js                 # Реактивное централизованное хранилище состояния
 │   ├── telegram/
 │   │   ├── client.js            # Создание и управление MTProto клиентом
+│   │   ├── socket.js            # Сетевой транспорт MTProto и туннелирование прокси (HTTP/SOCKS5)
 │   │   ├── auth.js              # Интерактивный логин-визард и 2FA
 │   │   ├── dialogs.js           # Получение, фильтрация и поиск диалогов
 │   │   ├── messages.js          # Загрузка истории, отправка, правка, файлы, реакции

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@emaxe/tuigram",
-  "version": "1.0.1",
+  "version": "1.1.0",
   "description": "Полнофункциональный TUI & CLI клиент Telegram на Node.js на базе MTProto (teleproto)",
   "type": "module",
   "exports": {

package/src/cli/init.js

@@ -2,7 +2,7 @@ import fs from "node:fs";
 import path from "node:path";
 import input from "input";
 import { bold, cyan, green, yellow, dim } from "colorette";
-import { config } from "../config.js";
+import { config, formatProxyUrl } from "../config.js";
 
 /** Сколько раз переспрашивать значение, прежде чем сдаться. */
 const MAX_ATTEMPTS = 3;
@@ -193,5 +193,6 @@ export function cmdPaths() {
     console.log(`  Сессия:          ${config.sessionPath} ${sessionExists ? green("(есть)") : dim("(нет)")}`);
     console.log(`  Загрузки:        ${config.downloadsDir}`);
     console.log(`  Ключи API:       ${config.apiId && config.apiHash ? green("заданы") : yellow("не заданы — запустите tuigram init")}`);
+    console.log(`  Прокси:          ${config.proxy ? green(formatProxyUrl(config.proxy)) : dim("не используется")}`);
     console.log("");
 }

package/src/config.js

@@ -110,6 +110,129 @@ function readVersion() {
     }
 }
 
+/**
+ * @typedef {Object} ProxyConfig
+ * @property {"http"|"https"|"socks5"|"socks4"} type - Протокол прокси
+ * @property {string} host - Адрес сервера прокси
+ * @property {number} port - Порт сервера прокси
+ * @property {string} [username] - Логин пользователя
+ * @property {string} [password] - Пароль пользователя
+ * @property {number} [timeout] - Таймаут в секундах
+ * @property {string} ip - Хост прокси (для совместимости с MTProto)
+ * @property {4|5} [socksType] - Тип SOCKS-прокси
+ * @property {boolean} [http] - Флаг HTTP-прокси
+ */
+
+/**
+ * Нормализует тип прокси из строки протокола.
+ * @param {string} [raw]
+ * @returns {"http"|"https"|"socks5"|"socks4"}
+ */
+function normalizeProxyType(raw) {
+    const clean = String(raw || "").toLowerCase().replace(/:$/, "").trim();
+    if (clean === "https") return "https";
+    if (clean === "socks4" || clean === "socks4a") return "socks4";
+    if (clean === "socks5" || clean === "socks5h" || clean === "socks") return "socks5";
+    return "http";
+}
+
+/**
+ * Разбирает параметры прокси из переменных окружения или переданного объекта.
+ * Поддерживает URL-формат (PROXY_URL, HTTPS_PROXY, HTTP_PROXY, ALL_PROXY)
+ * и отдельные переменные (PROXY_TYPE, PROXY_HOST, PROXY_PORT, PROXY_USERNAME, PROXY_PASSWORD).
+ * @param {Record<string, string|undefined>} [env=process.env]
+ * @returns {ProxyConfig|null}
+ */
+export function parseProxyConfig(env = process.env) {
+    const rawUrl = env.PROXY_URL || env.proxy_url || (!env.PROXY_HOST && !env.PROXY_IP && !env.proxy_host && !env.proxy_ip
+        ? (env.HTTPS_PROXY || env.https_proxy || env.HTTP_PROXY || env.http_proxy || env.ALL_PROXY || env.all_proxy)
+        : undefined);
+
+    let type = "http";
+    let host = "";
+    let port = 0;
+    let username = "";
+    let password = "";
+
+    if (rawUrl && typeof rawUrl === "string" && rawUrl.trim()) {
+        let urlStr = rawUrl.trim();
+        // Добавляем схему по умолчанию, если передан host:port без префикса
+        if (!/^[a-zA-Z0-9+-.]+:\/\//.test(urlStr)) {
+            const defaultScheme = (env.PROXY_TYPE || "http").toLowerCase().replace(/:$/, "");
+            urlStr = `${defaultScheme}://${urlStr}`;
+        }
+
+        try {
+            const parsed = new URL(urlStr);
+            type = normalizeProxyType(parsed.protocol);
+            host = parsed.hostname.replace(/^\[(.*)\]$/, "$1");
+            port = parsed.port ? parseInt(parsed.port, 10) : (type === "https" ? 443 : (type.startsWith("socks") ? 1080 : 8080));
+            if (parsed.username) username = decodeURIComponent(parsed.username);
+            if (parsed.password) password = decodeURIComponent(parsed.password);
+        } catch {
+            return null;
+        }
+    } else if (env.PROXY_HOST || env.PROXY_IP) {
+        type = normalizeProxyType(env.PROXY_TYPE || "http");
+        host = String(env.PROXY_HOST || env.PROXY_IP).trim();
+        const defaultPort = type === "https" ? 443 : (type.startsWith("socks") ? 1080 : 8080);
+        port = env.PROXY_PORT ? parseInt(String(env.PROXY_PORT).trim(), 10) : defaultPort;
+        username = String(env.PROXY_USERNAME || env.PROXY_USER || "").trim();
+        password = String(env.PROXY_PASSWORD || env.PROXY_PASS || "").trim();
+    } else {
+        return null;
+    }
+
+    if (!host || !port || isNaN(port) || port <= 0 || port > 65535) {
+        return null;
+    }
+
+    const rawTimeout = env.PROXY_TIMEOUT ? parseInt(String(env.PROXY_TIMEOUT).trim(), 10) : 10;
+    const timeout = isNaN(rawTimeout) || rawTimeout <= 0 ? 10 : rawTimeout;
+
+    /** @type {ProxyConfig} */
+    const result = {
+        type,
+        host,
+        port,
+        ip: host,
+        timeout,
+    };
+
+    if (username) result.username = username;
+    if (password) result.password = password;
+
+    if (type === "socks5") {
+        result.socksType = 5;
+    } else if (type === "socks4") {
+        result.socksType = 4;
+    } else {
+        result.http = true;
+    }
+
+    return result;
+}
+
+/**
+ * Форматирует конфигурацию прокси в строку для вывода в терминал.
+ * Пароль маскируется звездочками в целях безопасности.
+ * @param {ProxyConfig|null} proxy
+ * @returns {string}
+ */
+export function formatProxyUrl(proxy) {
+    if (!proxy) return "не используется";
+
+    let auth = "";
+    if (proxy.username) {
+        auth = proxy.password
+            ? `${encodeURIComponent(proxy.username)}:***@`
+            : `${encodeURIComponent(proxy.username)}@`;
+    }
+
+    const host = proxy.host.includes(":") ? `[${proxy.host}]` : proxy.host;
+    return `${proxy.type}://${auth}${host}:${proxy.port}`;
+}
+
 export const config = {
     packageRoot,
     /** @deprecated оставлено для обратной совместимости, равно packageRoot */
@@ -129,6 +252,8 @@ export const config = {
     autoScroll: String(process.env.AUTO_SCROLL || "true").toLowerCase() === "true",
     showTyping: String(process.env.SHOW_TYPING || "true").toLowerCase() === "true",
 
+    proxy: parseProxyConfig(),
+
     /**
      * Путь к файлу сессии.
      * @returns {string}

package/src/telegram/client.js

@@ -4,6 +4,7 @@ import { StringSession } from "teleproto/sessions/index.js";
 import { Logger, LogLevel } from "teleproto/extensions/Logger.js";
 import { config } from "../config.js";
 import { saveSessionFile, readFileSafe } from "../utils/storage.js";
+import { TuiGramNetSockets } from "./socket.js";
 
 /**
  * Читает сохранённую строку сессии.
@@ -42,17 +43,24 @@ export function clearSession() {
 export function buildClient(sessionString = readSession()) {
     config.assertCredentials();
 
+    const clientParams = {
+        connectionRetries: 10,
+        autoReconnect: true,
+        retryDelay: 1500,
+        baseLogger: new Logger(LogLevel.ERROR),
+        useWSS: false,
+    };
+
+    if (config.proxy) {
+        clientParams.proxy = config.proxy;
+        clientParams.networkSocket = TuiGramNetSockets;
+    }
+
     const client = new TelegramClient(
         new StringSession(sessionString),
         config.apiId,
         config.apiHash,
-        {
-            connectionRetries: 10,
-            autoReconnect: true,
-            retryDelay: 1500,
-            baseLogger: new Logger(LogLevel.ERROR),
-            useWSS: false,
-        }
+        clientParams
     );
 
     return client;

package/src/telegram/socket.js

@@ -0,0 +1,224 @@
+/**
+ * Сетевой транспорт для MTProto с поддержкой прокси (HTTP CONNECT, SOCKS5, SOCKS4).
+ */
+import http from "node:http";
+import https from "node:https";
+import net from "node:net";
+import { PromisedNetSockets } from "teleproto/extensions/PromisedNetSockets.js";
+import { SocksClient } from "socks";
+
+/**
+ * Создаёт TCP-туннель через HTTP/HTTPS прокси методом HTTP CONNECT.
+ * Поддерживает как прокси с Basic-авторизацией, так и без неё.
+ * @param {object} params
+ * @param {boolean} [params.isHttps=false] подключение к прокси-серверу по TLS
+ * @param {string} params.proxyHost адрес прокси-сервера
+ * @param {number} params.proxyPort порт прокси-сервера
+ * @param {string} params.targetHost адрес целевого сервера Telegram MTProto
+ * @param {number} params.targetPort порт целевого сервера Telegram MTProto
+ * @param {string} [params.username] логин для авторизации на прокси
+ * @param {string} [params.password] пароль для авторизации на прокси
+ * @param {number} [params.timeout=10000] таймаут установки соединения в миллисекундах
+ * @returns {Promise<import("node:net").Socket>}
+ */
+export function createHttpConnectSocket({
+    isHttps = false,
+    proxyHost,
+    proxyPort,
+    targetHost,
+    targetPort,
+    username,
+    password,
+    timeout = 10000,
+}) {
+    return new Promise((resolve, reject) => {
+        const clientModule = isHttps ? https : http;
+
+        const headers = {
+            Host: `${targetHost}:${targetPort}`,
+            "User-Agent": "TuiGram",
+            "Proxy-Connection": "Keep-Alive",
+        };
+
+        if (username || password) {
+            const auth = Buffer.from(`${username || ""}:${password || ""}`).toString("base64");
+            headers["Proxy-Authorization"] = `Basic ${auth}`;
+        }
+
+        const req = clientModule.request({
+            host: proxyHost,
+            port: proxyPort,
+            method: "CONNECT",
+            path: `${targetHost}:${targetPort}`,
+            headers,
+            timeout,
+        });
+
+        let finished = false;
+
+        const cleanup = () => {
+            req.removeAllListeners();
+        };
+
+        req.on("connect", (res, socket, head) => {
+            if (finished) return;
+            finished = true;
+            cleanup();
+
+            if (res.statusCode >= 200 && res.statusCode < 300) {
+                // Если в заголовке ответа уже были данные следующего протокола, возвращаем их в сокет
+                if (head && head.length > 0) {
+                    socket.unshift(head);
+                }
+                resolve(socket);
+            } else if (res.statusCode === 407) {
+                socket.destroy();
+                reject(new Error("Ошибка авторизации на HTTP-прокси (407 Proxy Authentication Required)"));
+            } else {
+                socket.destroy();
+                reject(new Error(`HTTP-прокси вернул код ошибки: ${res.statusCode} ${res.statusMessage || ""}`.trim()));
+            }
+        });
+
+        req.on("response", (res) => {
+            if (finished) return;
+            finished = true;
+            cleanup();
+            if (res.statusCode === 407) {
+                reject(new Error("Ошибка авторизации на HTTP-прокси (407 Proxy Authentication Required)"));
+            } else {
+                reject(new Error(`HTTP-прокси вернул код ошибки: ${res.statusCode} ${res.statusMessage || ""}`.trim()));
+            }
+        });
+
+        req.on("timeout", () => {
+            if (finished) return;
+            finished = true;
+            cleanup();
+            req.destroy(new Error(`Таймаут подключения к HTTP-прокси (${proxyHost}:${proxyPort})`));
+        });
+
+        req.on("error", (err) => {
+            if (finished) return;
+            finished = true;
+            cleanup();
+            reject(new Error(`Не удалось подключиться к HTTP-прокси (${proxyHost}:${proxyPort}): ${err.message}`));
+        });
+
+        req.end();
+    });
+}
+
+/**
+ * Расширенный сокет для teleproto с поддержкой HTTP CONNECT и SOCKS5/4 туннелирования.
+ */
+export class TuiGramNetSockets extends PromisedNetSockets {
+    /**
+     * @param {object} [proxy]
+     * @param {number} [keepAliveInterval]
+     */
+    constructor(proxy, keepAliveInterval) {
+        // Передаём undefined в базовый класс, чтобы обойти валидацию socksType для HTTP-прокси
+        super(undefined, keepAliveInterval);
+        this.proxy = proxy;
+    }
+
+    /**
+     * Устанавливает сетевое соединение с дата-центром Telegram.
+     * @param {number} port
+     * @param {string} ip
+     * @returns {Promise<this>}
+     */
+    async connect(port, ip) {
+        this.chunks = [];
+        this.headOffset = 0;
+        this.available = 0;
+        let connected = false;
+
+        if (this.proxy) {
+            const proxyType = (this.proxy.type || "").toLowerCase();
+            const host = this.proxy.host || this.proxy.ip;
+            const proxyPort = Number(this.proxy.port);
+            const timeout = (this.proxy.timeout || 10) * 1000;
+
+            if (proxyType === "socks5" || proxyType === "socks4" || this.proxy.socksType) {
+                const socksType = this.proxy.socksType || (proxyType === "socks4" ? 4 : 5);
+                const info = await SocksClient.createConnection({
+                    proxy: {
+                        host,
+                        port: proxyPort,
+                        type: socksType,
+                        userId: this.proxy.username,
+                        password: this.proxy.password,
+                    },
+                    command: "connect",
+                    timeout,
+                    destination: {
+                        host: ip,
+                        port: port,
+                    },
+                });
+                this.client = info.socket;
+                connected = true;
+            } else if (proxyType === "http" || proxyType === "https" || this.proxy.http) {
+                this.client = await createHttpConnectSocket({
+                    isHttps: proxyType === "https",
+                    proxyHost: host,
+                    proxyPort: proxyPort,
+                    targetHost: ip,
+                    targetPort: port,
+                    username: this.proxy.username,
+                    password: this.proxy.password,
+                    timeout,
+                });
+                connected = true;
+            } else {
+                throw new Error(`Неподдерживаемый тип прокси: ${this.proxy.type}`);
+            }
+        } else {
+            this.client = new net.Socket();
+        }
+
+        this.canRead = new Promise((resolve) => {
+            this.resolveRead = resolve;
+        });
+        this.closed = false;
+
+        return new Promise((resolve, reject) => {
+            if (!this.client) {
+                return reject(new Error("Сетевой сокет не инициализирован"));
+            }
+
+            const tune = (socket) => {
+                socket.setNoDelay(true);
+                socket.setKeepAlive(this.keepAliveInterval > 0, Math.max(0, this.keepAliveInterval));
+            };
+
+            if (connected) {
+                tune(this.client);
+                this.receive();
+                resolve(this);
+            } else {
+                this.client.connect(port, ip, () => {
+                    tune(this.client);
+                    this.receive();
+                    resolve(this);
+                });
+            }
+
+            this.client.on("error", reject);
+            this.client.on("close", () => {
+                if (this.client && this.client.destroyed) {
+                    if (this.resolveRead) {
+                        this.resolveRead(false);
+                    }
+                    this.closed = true;
+                }
+            });
+        });
+    }
+
+    toString() {
+        return "TuiGramNetSocket";
+    }
+}