supertelegram 0.5.0 → 0.6.0

package/README.md

@@ -128,6 +128,22 @@ TELEGRAM_SESSION=./custom.txt telegram send @friend "hey"
 4. `./session.txt` (backwards compat)
 5. `~/.supertelegram/session.txt` (legacy default)
 
+## websocket transport (blocked mtproto)
+
+some networks (cloud sandboxes, agent runtimes, corporate proxies) let tcp reach
+telegram DC ips but kill the raw mtproto handshake — login dies with
+`Not connected` on `ReqPqMulti`. switch to the same wss path web telegram uses:
+
+```bash
+TELEGRAM_WSS=1 telegram login
+# or persist it
+telegram config set wss true
+```
+
+this talks to `*.web.telegram.org/apiws` over tls 443 with the obfuscated
+transport. login, messages and media all work; only the transport changes.
+needs bun or node >= 22 (native WebSocket).
+
 ## development
 
 clone repo and install:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "supertelegram",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "telegram cli for humans and bots",
   "module": "index.ts",
   "type": "module",

package/src/cli/commands.ts

@@ -10,7 +10,7 @@ import {
   downloadMedia as telegramDownloadMedia,
 } from "../client/telegram";
 import { askPhoneNumber, askPhoneCode, askPassword, askAppId, askAppHash } from "./prompts";
-import { getApiCredentials, setConfig } from "../config/manager";
+import { getApiCredentials, getConfig, setConfig } from "../config/manager";
 import {
   listAccounts,
   setCurrentAccount,
@@ -294,6 +294,8 @@ export async function config(action?: string, key?: string, value?: string) {
       console.log(cfg.appId);
     } else if (key === "appHash" && cfg) {
       console.log(cfg.appHash);
+    } else if (key === "wss") {
+      console.log(String(getConfig().wss === "true"));
     } else {
       console.log("not found");
     }
@@ -303,6 +305,7 @@ export async function config(action?: string, key?: string, value?: string) {
   console.log("usage:");
   console.log("  telegram config set appId <id>");
   console.log("  telegram config set appHash <hash>");
+  console.log("  telegram config set wss true    (websocket transport for networks blocking mtproto)");
   console.log("  telegram config get appId");
 }
 

package/src/cli/run.ts

@@ -1,4 +1,5 @@
 #!/usr/bin/env bun
+import { explainConnectionError } from "../client/wss";
 import { send, read, dialogs, unread, reply, login, config, sendFile, downloadMedia, accounts, switchAccount, logout, whoami } from "./commands";
 import { setVerbose, setSessionPath } from "../client/telegram";
 import { migrateLegacyIfNeeded, accountSessionPath } from "../config/accounts";
@@ -26,7 +27,7 @@ commands:
   switch <name>              switch the active account
   whoami                     show the active account
   logout [name]              remove an account (default: current)
-  config set <key> <val>     set API credentials (appId, appHash)
+  config set <key> <val>     set API credentials (appId, appHash) or wss true
 
 options:
   -a, --account <name>     run this command as a specific account
@@ -170,7 +171,10 @@ async function main() {
   }
 }
 
-main().catch((err) => {
-  console.error("error:", err.message);
+function die(err: unknown) {
+  console.error("error:", explainConnectionError(err).message);
   process.exit(1);
-});
+}
+
+process.on("unhandledRejection", die);
+main().catch(die);

package/src/client/telegram.ts

@@ -4,6 +4,7 @@ import { Logger } from "telegram/extensions/Logger";
 import type { LogLevel } from "telegram/extensions/Logger";
 import { loadSession, saveSession } from "../session/storage";
 import { getApiCredentials } from "../config/manager";
+import { wssEnabled, wssClientParams, applyWss, restoreTcpDc, explainConnectionError } from "./wss";
 
 let verbose = false;
 
@@ -46,9 +47,17 @@ export async function getClient(): Promise<TelegramClient> {
   client = new TelegramClient(session, creds.appId, creds.appHash, {
     connectionRetries: 5,
     baseLogger: new SilentLogger(),
+    ...(wssEnabled() ? wssClientParams : {}),
   });
 
-  await client.connect();
+  if (wssEnabled()) applyWss(client);
+  else restoreTcpDc(client);
+
+  try {
+    await client.connect();
+  } catch (err) {
+    throw explainConnectionError(err);
+  }
   return client;
 }
 

package/src/client/wss.ts

@@ -0,0 +1,162 @@
+import type { TelegramClient } from "telegram";
+import { ConnectionTCPObfuscated } from "telegram/network";
+
+import { wssEnabled } from "../config/manager";
+export { wssEnabled };
+
+const WEB_DC_HOSTS: Record<number, string> = {
+  1: "pluto",
+  2: "venus",
+  3: "aurora",
+  4: "vesta",
+  5: "flora",
+};
+
+const TCP_DC_IPS: Record<number, string> = {
+  1: "149.154.175.53",
+  2: "149.154.167.51",
+  3: "149.154.175.100",
+  4: "149.154.167.91",
+  5: "91.108.56.130",
+};
+
+export function isWebHost(host: string): boolean {
+  return host.endsWith(".web.telegram.org");
+}
+
+export function restoreTcpDc(client: TelegramClient): void {
+  const host = client.session.serverAddress;
+  if (!host || !isWebHost(host)) return;
+  const dcId = client.session.dcId;
+  const ip = TCP_DC_IPS[dcId];
+  if (!ip) throw new Error(`no tcp ip for DC ${dcId}`);
+  client.session.setDC(dcId, ip, 443);
+}
+
+export const MTPROTO_BLOCKED_HINT =
+  "mtproto handshake failed — this network likely blocks raw telegram DC traffic.\n" +
+  "retry over websockets: TELEGRAM_WSS=1 or `telegram config set wss true`";
+
+export function explainConnectionError(err: unknown): Error {
+  const msg = err instanceof Error ? err.message : String(err);
+  if (!wssEnabled() && msg.includes("Not connected")) {
+    return new Error(`${MTPROTO_BLOCKED_HINT}\noriginal: ${msg}`);
+  }
+  return err instanceof Error ? err : new Error(msg);
+}
+
+export function webDcHost(dcId: number, download = false): string {
+  const name = WEB_DC_HOSTS[dcId];
+  if (!name) throw new Error(`no web host for DC ${dcId}`);
+  return `${name}${download ? "-1" : ""}.web.telegram.org`;
+}
+
+const closeError = new Error("WebSocket was closed");
+
+// gramjs ships PromisedWebSockets on top of the `websocket` npm package,
+// which breaks under bun (101 upgrade surfaces as a plain http response).
+// native WebSocket exists in bun and node >= 22, so use that instead.
+// same read/write shape gramjs' Connection expects.
+class NativeWebSocket {
+  private ws?: WebSocket;
+  private stream = Buffer.alloc(0);
+  private closed = true;
+  private canRead!: Promise<boolean>;
+  private resolveRead?: (value: boolean) => void;
+
+  private resetRead() {
+    this.canRead = new Promise((resolve) => {
+      this.resolveRead = resolve;
+    });
+  }
+
+  getWebSocketLink(host: string, port: number, testServers: boolean): string {
+    const scheme = port === 443 ? "wss" : "ws";
+    return `${scheme}://${host}/apiws${testServers ? "_test" : ""}`;
+  }
+
+  async connect(port: number, host: string, testServers = false): Promise<this> {
+    if (typeof WebSocket === "undefined") {
+      throw new Error("wss transport needs a native WebSocket (bun or node >= 22)");
+    }
+    this.stream = Buffer.alloc(0);
+    this.resetRead();
+    this.closed = false;
+    const url = this.getWebSocketLink(host, port, testServers);
+    const ws = new WebSocket(url, "binary");
+    ws.binaryType = "arraybuffer";
+    this.ws = ws;
+
+    return new Promise((resolve, reject) => {
+      ws.onopen = () => resolve(this);
+      ws.onerror = (event) => {
+        reject(new Error(`wss connect to ${url} failed: ${(event as ErrorEvent).message ?? "unknown"}`));
+      };
+      ws.onclose = () => {
+        this.closed = true;
+        this.resolveRead?.(false);
+      };
+      ws.onmessage = (message) => {
+        this.stream = Buffer.concat([this.stream, Buffer.from(message.data as ArrayBuffer)]);
+        this.resolveRead?.(true);
+      };
+    });
+  }
+
+  async read(number: number): Promise<Buffer> {
+    if (this.closed) throw closeError;
+    await this.canRead;
+    if (this.closed) throw closeError;
+    const toReturn = this.stream.subarray(0, number);
+    this.stream = this.stream.subarray(number);
+    if (this.stream.length === 0) this.resetRead();
+    return toReturn;
+  }
+
+  async readExactly(number: number): Promise<Buffer> {
+    let readData = Buffer.alloc(0);
+    while (number > 0) {
+      const chunk = await this.read(number);
+      readData = Buffer.concat([readData, chunk]);
+      number -= chunk.length;
+    }
+    return readData;
+  }
+
+  async readAll(): Promise<Buffer> {
+    if (this.closed || !(await this.canRead)) throw closeError;
+    const toReturn = this.stream;
+    this.stream = Buffer.alloc(0);
+    this.resetRead();
+    return toReturn;
+  }
+
+  write(data: Buffer) {
+    if (this.closed) throw closeError;
+    this.ws?.send(data);
+  }
+
+  async close() {
+    this.ws?.close();
+    this.closed = true;
+  }
+
+  toString() {
+    return "NativeWebSocket";
+  }
+}
+
+export const wssClientParams = {
+  useWSS: true,
+  networkSocket: NativeWebSocket as any,
+  connection: ConnectionTCPObfuscated,
+} as const;
+
+export function applyWss(client: TelegramClient): void {
+  const dcId = client.session.dcId || 2;
+  client.session.setDC(dcId, webDcHost(dcId), 443);
+
+  const original = client.getDC.bind(client);
+  client.getDC = (id: number, downloadDC = false) =>
+    original(id, downloadDC, true);
+}

package/src/config/manager.ts

@@ -10,6 +10,7 @@ const SESSION_FILE = join(CONFIG_DIR, "session.txt");
 export interface Config {
   appId?: string;
   appHash?: string;
+  wss?: string;
 }
 
 function ensureConfigDir() {
@@ -72,6 +73,12 @@ export function getSessionPath(customPath?: string): string {
   return SESSION_FILE;
 }
 
+export function wssEnabled(): boolean {
+  const env = process.env.TELEGRAM_WSS;
+  if (env !== undefined) return env === "1" || env === "true";
+  return getConfig().wss === "true";
+}
+
 export function getApiCredentials(): { appId: number; appHash: string } | null {
   // precedence:
   // 1. env vars