mtproto-checker 0.1.0 → 0.1.2

package/README.md

@@ -1,34 +1,34 @@
-# MTProto Checker ⚡
+# MTProto Checker
 
-Fast Telegram MTProto proxy checker powered by TDLib. It does a real `testProxy`
-handshake through every proxy, so a green result means the proxy is much more
-likely to work in Telegram than with a plain TCP/TLS port check.
+Telegram MTProto proxy checker powered by TDLib. It runs a real `testProxy`
+handshake through each proxy, so a successful result is closer to "works in
+Telegram" than a plain TCP/TLS port check.
 
-## What It Does
+## Features
 
-- ✅ Parses `tg://proxy` and `https://t.me/proxy` links
-- 🌐 Loads proxy lists from remote URLs, local files, or `stdin`
-- 🧹 Removes duplicates by `server:port:secret`
-- 🔐 Supports hex and base64url MTProto secrets
-- 🕵️ Extracts Fake-TLS SNI from `ee...` secrets and supports padded `dd...` secrets
-- 🚀 Checks proxies concurrently via TDLib `testProxy`
-- 💪 Re-checks survivors with `--iterations` to find the most stable proxies
-- 📄 Writes both a full JSON report and a ready-to-use TXT list
+- Parses `tg://proxy` and `https://t.me/proxy` links.
+- Loads proxies from direct links, remote lists, local files, or `stdin`.
+- De-duplicates by `server:port:secret`.
+- Supports hex and base64url secrets, including Fake-TLS SNI extraction.
+- Checks proxies concurrently and can re-check only successful proxies across
+  multiple iterations.
+- Works as a CLI, HTTP API server, or CommonJS library.
 
 ## Requirements
 
-- Node.js 18+ recommended
-- npm
-- Telegram API credentials:
-  - `TG_API_ID`
-  - `TG_API_HASH`
+- Node.js 18+
+- Telegram API credentials: `TG_API_ID` and `TG_API_HASH`
 
-Get API credentials from [my.telegram.org](https://my.telegram.org).
+Get credentials from [my.telegram.org](https://my.telegram.org). No Telegram
+login or phone number is required; credentials are only used to initialize TDLib.
 
-> No Telegram login or phone number is required. The credentials are only used
-> to initialize TDLib before running `testProxy`.
+## Install
 
-## Installation
+```bash
+npm install mtproto-checker
+```
+
+For local development:
 
 ```bash
 git clone git@github.com:Tar4s/mtproto-checker.git
@@ -36,183 +36,102 @@ cd mtproto-checker
 npm install
 ```
 
-Optional, if you want the `check-proxies` command available locally:
-
-```bash
-npm link
-```
-
-### GitHub Packages
-
-This project can also be published to GitHub Packages as
-`@tar4s/mtproto-checker`. GitHub's npm registry requires scoped package names,
-so the GitHub Packages workflow applies that scoped name during publishing.
-
-To install from GitHub Packages:
+GitHub Packages users can install the scoped package:
 
 ```bash
 npm config set @tar4s:registry https://npm.pkg.github.com
 npm install @tar4s/mtproto-checker
 ```
 
-Private packages require authentication with a GitHub personal access token that
-has `read:packages`.
-
-## Quick Start
-
-Start the HTTP API server:
-
-```bash
-TG_API_ID=12345 \
-TG_API_HASH=abcdef \
-CHECK_AUTH_USER=admin \
-CHECK_AUTH_PASSWORD=secret \
-node check.js
-```
-
-By default it listens on port `3080`. Override it with `PORT`.
-
-Check URLs listed in `urls.txt`:
-
-```bash
-TG_API_ID=12345 TG_API_HASH=abcdef npm start -- --sources urls.txt
-```
-
-Equivalent direct Node.js run:
-
-```bash
-TG_API_ID=12345 TG_API_HASH=abcdef node check.js --sources urls.txt
-```
-
-With `npm link`:
+Private GitHub Packages require a token with `read:packages`.
 
-```bash
-TG_API_ID=12345 TG_API_HASH=abcdef check-proxies --sources urls.txt
-```
-
-Check one proxy link directly:
+## CLI
 
 ```bash
-TG_API_ID=12345 TG_API_HASH=abcdef node check.js \
-  --proxy 'tg://proxy?server=quackton.life&port=443&secret=7mX8dVOh9cqLULccAVs4ciR5YW5kZXgucnU'
+TG_API_ID=12345 TG_API_HASH=abcdef npx mtproto-checker --sources urls.txt
 ```
 
-## Input Sources
-
-You can provide proxies in several ways.
-
-### 1. Direct Proxy Link
+Common inputs:
 
 ```bash
+# One direct proxy link
 TG_API_ID=12345 TG_API_HASH=abcdef node check.js \
-  --proxy 'https://t.me/proxy?server=1.2.3.4&port=443&secret=...'
-```
-
-### 2. Source URL File
-
-`urls.txt` contains one remote text-list URL per line:
-
-```txt
-https://example.com/proxies.txt
-https://example.com/more-proxies.txt
-```
-
-Run:
-
-```bash
-TG_API_ID=12345 TG_API_HASH=abcdef node check.js --sources urls.txt
-```
-
-### 3. One Or More Remote URLs
+  --proxy 'tg://proxy?server=1.2.3.4&port=443&secret=...'
 
-```bash
+# One or more remote proxy-list URLs
 TG_API_ID=12345 TG_API_HASH=abcdef node check.js \
   --url https://example.com/proxies.txt \
-  --url https://example.com/more-proxies.txt
-```
-
-Positional HTTP URLs also work:
-
-```bash
-TG_API_ID=12345 TG_API_HASH=abcdef node check.js https://example.com/proxies.txt
-```
+  --url https://example.com/more.txt
 
-### 4. Local Proxy File
-
-```bash
+# Source URL file, local proxy file, or stdin
+TG_API_ID=12345 TG_API_HASH=abcdef node check.js --sources urls.txt
 TG_API_ID=12345 TG_API_HASH=abcdef node check.js proxies.txt
-```
-
-### 5. stdin
-
-```bash
 cat proxies.txt | TG_API_ID=12345 TG_API_HASH=abcdef node check.js
 ```
 
-Input files may contain blank lines and `#` comments.
-
-## CLI Options
+Options:
 
 | Option | Default | Description |
 | --- | ---: | --- |
-| `--url <url>` | none | Add a remote proxy-list URL. Can be repeated. |
 | `--proxy <link>` | none | Check one `tg://proxy` or `https://t.me/proxy` link directly. |
-| `--sources <file>` | none | Read remote source URLs from a file, one URL per line. |
-| `--dc <1-5>` | `2` | Telegram data center ID used for `testProxy`. |
-| `--timeout <sec>` | `10` | Per-proxy TDLib timeout in seconds. Decimals are allowed. |
-| `--concurrency <n>` | `30` | Number of proxies checked in parallel. Lower values can produce steadier latency numbers. |
-| `--iterations <num>` | `1` | Number of check rounds. Each next round checks only proxies that passed the previous one. |
-| `--out <prefix>` | `result` | Output file prefix. Writes `<prefix>.json` and `<prefix>.txt`. |
-
-Environment variables:
-
-| Variable | Required | Description |
-| --- | --- | --- |
-| `TG_API_ID` | yes | Telegram API ID from `my.telegram.org`. |
-| `TG_API_HASH` | yes | Telegram API hash from `my.telegram.org`. |
-| `CHECK_AUTH_USER` | HTTP server only | Basic auth username. |
-| `CHECK_AUTH_PASSWORD` | HTTP server only | Basic auth password. |
-| `PORT` | no | HTTP server port. Defaults to `3080`. |
+| `--url <url>` | none | Add a remote proxy-list URL. Repeatable. |
+| `--sources <file>` | none | Read remote source URLs from a file. |
+| `--dc <1-5>` | `2` | Telegram data center used for `testProxy`. |
+| `--timeout <sec>` | `10` | Per-proxy TDLib timeout. |
+| `--concurrency <n>` | `30` | Parallel proxy checks. |
+| `--iterations <n>` | `1` | Re-check only successful proxies for `n` rounds. |
+| `--out <prefix>` | `result` | Writes `<prefix>.json` and `<prefix>.txt`. |
+
+Input files may contain blank lines and `#` comments. Only MTProto proxy links
+are checked; `tg://socks` links are ignored.
 
 ## HTTP API
 
-Running `node check.js` without CLI arguments starts the HTTP server. The server
-requires Basic auth and exposes one endpoint:
+Running `node check.js` without arguments starts the server on `PORT` or `3080`.
+Basic auth is required.
+
+```bash
+TG_API_ID=12345 \
+TG_API_HASH=abcdef \
+CHECK_AUTH_USER=admin \
+CHECK_AUTH_PASSWORD=secret \
+node check.js
+```
+
+Endpoint:
 
 ```http
 POST /check
 Content-Type: application/json
 Authorization: Basic ...
 
-{ "url": "https://example.com/proxies.txt" }
+{
+  "url": "https://example.com/proxies.txt",
+  "iterations": 3,
+  "concurrency": 10
+}
 ```
 
-The `url` field accepts either a remote `http(s)` proxy list or one direct
-`tg://proxy` / `https://t.me/proxy` link.
+`url` accepts either a remote `http(s)` proxy list or one direct `tg://proxy` /
+`https://t.me/proxy` link. `iterations` defaults to `1`; `concurrency` defaults
+to `30`.
 
 Example:
 
 ```bash
 curl -u admin:secret \
   -H 'content-type: application/json' \
-  -d '{"url":"https://example.com/proxies.txt"}' \
-  http://127.0.0.1:3080/check
-```
-
-Direct proxy link example:
-
-```bash
-curl -u admin:secret \
-  -H 'content-type: application/json' \
-  -d '{"url":"tg://proxy?server=quackton.life&port=443&secret=7mX8dVOh9cqLULccAVs4ciR5YW5kZXgucnU"}' \
+  -d '{"url":"tg://proxy?server=1.2.3.4&port=443&secret=...","iterations":3,"concurrency":10}' \
   http://127.0.0.1:3080/check
 ```
 
-Response:
+Response shape:
 
 ```json
 {
   "url": "https://example.com/proxies.txt",
+  "iterations": 3,
+  "concurrency": 10,
   "count": 1,
   "working": 1,
   "results": [
@@ -229,88 +148,27 @@ Response:
 }
 ```
 
-## Output
-
-By default the checker writes:
+## Library Usage
 
-- `result.json` — full report for the final completed round
-- `result.txt` — working proxy links from the final completed round, fastest first
-
-Example JSON item:
+```js
+const { checkRequestUrl, checkProxiesFromUrls } = require('mtproto-checker')
 
-```json
-{
-  "server": "1.2.3.4",
-  "port": 443,
-  "sni": "example.com",
-  "ok": true,
-  "ms": 841,
-  "error": null,
-  "link": "tg://proxy?server=1.2.3.4&port=443&secret=..."
+const opts = {
+  apiId: Number(process.env.TG_API_ID),
+  apiHash: process.env.TG_API_HASH,
+  concurrency: 30,
+  iterations: 2
 }
-```
-
-Use a custom prefix:
-
-```bash
-TG_API_ID=12345 TG_API_HASH=abcdef node check.js --sources urls.txt --out fresh
-```
-
-This creates `fresh.json` and `fresh.txt`.
-
-## Practical Examples
-
-Fast broad scan:
-
-```bash
-TG_API_ID=12345 TG_API_HASH=abcdef node check.js --sources urls.txt --concurrency 80 --timeout 7
-```
-
-More conservative latency check:
-
-```bash
-TG_API_ID=12345 TG_API_HASH=abcdef node check.js --sources urls.txt --concurrency 10 --timeout 15
-```
-
-Find the most stable proxies across several rounds:
-
-```bash
-TG_API_ID=12345 TG_API_HASH=abcdef node check.js --sources urls.txt --iterations 3 --out stable
-```
-
-Test against another Telegram DC:
-
-```bash
-TG_API_ID=12345 TG_API_HASH=abcdef node check.js --sources urls.txt --dc 4
-```
 
-Check a pasted list:
+const direct = await checkRequestUrl('tg://proxy?server=1.2.3.4&port=443&secret=...', opts)
+const fromLists = await checkProxiesFromUrls(['https://example.com/proxies.txt'], opts)
 
-```bash
-pbpaste | TG_API_ID=12345 TG_API_HASH=abcdef node check.js --out pasted
+console.log(direct, fromLists)
 ```
 
-## Programmatic Usage
-
-```js
-const { checkProxiesFromUrls } = require('./check')
-
-const results = await checkProxiesFromUrls(
-  ['https://example.com/proxies.txt'],
-  {
-    apiId: Number(process.env.TG_API_ID),
-    apiHash: process.env.TG_API_HASH,
-    dc: 2,
-    timeout: 10,
-    concurrency: 30
-  }
-)
-
-console.log(results)
-```
-
-Exported helpers:
+Main exports:
 
+- `checkRequestUrl(url, opts)`
 - `checkProxiesFromUrls(urls, opts)`
 - `loadProxiesFromUrls(urls)`
 - `checkProxies(proxies, opts)`
@@ -319,15 +177,20 @@ Exported helpers:
 - `normalizeSecret(secret)`
 - `faketlsSni(hexSecret)`
 
-## Notes & Troubleshooting
+## Output
+
+CLI runs write:
+
+- `result.json` or `<out>.json`: full report for the final completed round.
+- `result.txt` or `<out>.txt`: working proxy links, fastest first.
+
+Use `--out fresh` to write `fresh.json` and `fresh.txt`.
+
+## Troubleshooting
 
-- If you see `Set TG_API_ID and TG_API_HASH`, export both credentials or prefix
-  the command with them.
-- If remote URLs fail on old Node.js versions, upgrade to Node.js 18+.
-- If checks are noisy, reduce `--concurrency`.
-- If you want only resilient proxies, increase `--iterations`; `result.txt`
-  will contain proxies that survived the final round.
-- Only MTProto proxy links are checked. `tg://socks` links are ignored.
+- `Set TG_API_ID and TG_API_HASH`: export both credentials or prefix the command.
+- Noisy latency: reduce `--concurrency`.
+- Need only stable proxies: increase `--iterations`.
 - Temporary TDLib files are created in `.proxy-checker-td/` and removed after the run.
 
 ## License

package/check.js

@@ -415,6 +415,31 @@ async function checkSingleUrl(url, opts) {
   return checker(proxies, opts)
 }
 
+async function loadSingleUrlProxies(url, opts = {}) {
+  const directProxy = parseLink(url)
+  if (directProxy) return [directProxy]
+
+  let parsed
+  try {
+    parsed = new URL(url)
+  } catch {
+    throw new Error('url must be a proxy link or an http or https URL')
+  }
+  if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
+    throw new Error('url must be a proxy link or an http or https URL')
+  }
+
+  const fetcher = opts.fetcher || fetchText
+  const text = await fetcher(url)
+  return mergeProxies([text])
+}
+
+async function checkRequestUrl(url, opts) {
+  const proxies = await loadSingleUrlProxies(url, opts)
+  const checker = opts.checker || checkProxies
+  return runIterativeChecks(proxies, opts.iterations ?? 1, batch => checker(batch, opts))
+}
+
 async function resolveInputProxies(opts, deps = {}) {
   const readFile = deps.readFile || (file => fs.readFileSync(file, 'utf8'))
   const readInputFn = deps.readInput || readInput
@@ -554,11 +579,23 @@ function createServer({ auth, checkUrl, logger = console.error }) {
         jsonResponse(res, statusCode, { error: 'Request body must include url' })
         return
       }
+      const iterations = body.iterations === undefined ? 1 : body.iterations
+      if (!Number.isInteger(iterations) || iterations < 1) {
+        statusCode = 400
+        jsonResponse(res, statusCode, { error: 'iterations must be a positive integer' })
+        return
+      }
+      const concurrency = body.concurrency === undefined ? 30 : body.concurrency
+      if (!Number.isInteger(concurrency) || concurrency < 1) {
+        statusCode = 400
+        jsonResponse(res, statusCode, { error: 'concurrency must be a positive integer' })
+        return
+      }
 
       const url = body.url.trim()
       let results
       try {
-        results = await checkUrl(url)
+        results = await checkUrl(url, { iterations, concurrency })
       } catch (err) {
         statusCode = 502
         jsonResponse(res, statusCode, {
@@ -571,6 +608,8 @@ function createServer({ auth, checkUrl, logger = console.error }) {
       statusCode = 200
       jsonResponse(res, statusCode, {
         url,
+        iterations,
+        concurrency,
         count: report.length,
         working: report.filter(item => item.ok).length,
         results: report
@@ -603,7 +642,12 @@ async function startServer(env = process.env) {
 
   const server = createServer({
     auth: { user, password },
-    checkUrl: async url => checkSingleUrl(url, { apiId, apiHash })
+    checkUrl: async (url, requestOpts) => checkRequestUrl(url, {
+      apiId,
+      apiHash,
+      iterations: requestOpts.iterations,
+      concurrency: requestOpts.concurrency
+    })
   })
 
   await new Promise((resolve, reject) => {
@@ -681,7 +725,7 @@ async function main() {
   process.exit(0)
 }
 
-module.exports = { checkSingleUrl, configureTdlibOnce, createServer, parseArgs, resolveInputProxies, checkProxiesFromUrls, loadProxiesFromUrls, checkProxies, runIterativeChecks, mergeProxies, parseLink, normalizeSecret, faketlsSni, shouldStartServer, startServer }
+module.exports = { checkRequestUrl, checkSingleUrl, configureTdlibOnce, createServer, parseArgs, resolveInputProxies, checkProxiesFromUrls, loadProxiesFromUrls, checkProxies, runIterativeChecks, mergeProxies, parseLink, normalizeSecret, faketlsSni, shouldStartServer, startServer }
 
 if (require.main === module) (shouldStartServer(process.argv.slice(2)) ? startServer() : main()).catch(err => {
   console.error(err)

package/package.json

@@ -1,10 +1,14 @@
 {
   "name": "mtproto-checker",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Check Telegram MTProto proxies via a real TDLib handshake (testProxy), like tdesktop does",
+  "main": "check.js",
+  "exports": {
+    ".": "./check.js"
+  },
   "repository": {
     "type": "git",
-    "url": "https://github.com/Tar4s/mtproto-checker"
+    "url": "git+https://github.com/Tar4s/mtproto-checker.git"
   },
   "bugs": {
     "url": "https://github.com/Tar4s/mtproto-checker/issues"
@@ -22,7 +26,7 @@
     "start": "node check.js"
   },
   "engines": {
-    "node": ">=16"
+    "node": ">=18"
   },
   "dependencies": {
     "tdl": "^8.0.2",