https://github.com/michaldziuba03/tor-client
Node.js Tor client without dependencies 🧅
https://github.com/michaldziuba03/tor-client
node-js nodejs tor tor-browser tor-client tor-network typescript
Last synced: about 1 year ago
JSON representation
Node.js Tor client without dependencies 🧅
- Host: GitHub
- URL: https://github.com/michaldziuba03/tor-client
- Owner: michaldziuba03
- License: mit
- Created: 2021-11-07T10:32:28.000Z (over 4 years ago)
- Default Branch: main
- Last Pushed: 2024-11-01T19:27:28.000Z (over 1 year ago)
- Last Synced: 2025-03-17T21:43:38.693Z (about 1 year ago)
- Topics: node-js, nodejs, tor, tor-browser, tor-client, tor-network, typescript
- Language: TypeScript
- Homepage:
- Size: 242 KB
- Stars: 22
- Watchers: 1
- Forks: 3
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
Node.js Tor client
A simple library for making HTTP requests over the Tor network programmatically in JavaScript.
> I do **NOT** recommend using this library with other runtimes such Deno or Bun.
> It relies on HTTP Agent and for example Bun is not using HTTP Agent in every context so you can end up with making HTTP request without Tor...
## 🧅 Features
- [x] Simple codebase
- [x] Own implementation of SOCKS5 protocol
- [x] Built-in HTTP wrapper (but still possible to use with `axios`)
- [x] Same `User-Agent` as in Tor Browser by default
- [x] Written in TypeScript
- [x] No external dependencies
### Install Tor
This library expects Tor proxy server to be available locally on port `9050` (by default).
#### Arch/Manjaro/Garuda (Linux)
```bash
$ sudo pacman -S tor
$ sudo systemctl enable tor.service
$ sudo systemctl start tor.service
```
##### Debian/Ubuntu/Mint (Linux)
```bash
$ sudo apt install tor
```
### Code example
```ts
const client = new TorClient();
const result = await client.get('https://check.torproject.org/');
// status (number):
console.log(result.status);
// data (string by default):
console.log(result.data);
// headers (object):
console.log(result.headers);
```
### Documentation
#### Configuration for `SOCKS5` proxy
```ts
const client = new TorClient({
socksHost: 'localhost'
socksPort: 2137,
});
```
By default client connects with `localhost:9050`.
#### Request options
By default request does **not** have any timeout.
```ts
{
headers: object,
timeout: number,
}
```
#### `.torcheck(options?)`
Ping `https://check.torproject.org/` to check Tor connection status.
```ts
const client = new TorClient();
const isUsed = await client.torcheck();
console.log(isUsed); // true or false
```
#### `.get(url, options?)`
Make http GET request (works with regular and `.onion` sites).
```ts
const client = new TorClient();
const url = 'https://duckduckgogg42xjoc72x3sjasowoarfbgcmvfimaftt6twagswzczad.onion/?q=tor';
const result = await client.get(url);
console.log(result.data); // HTML -> string
```
#### `.post(url, data, options?)`
Make http POST request (works with regular and `.onion` sites).
```ts
const client = new TorClient();
const url = 'https://duckduckgogg42xjoc72x3sjasowoarfbgcmvfimaftt6twagswzczad.onion/';
const result = await client.post(url, { q: 'tor' });
console.log(result.data); // HTML -> string
```
#### `.download(url, options?)`
Download response body to file (implementation based on Node.js Streams and works with binaries and text files)
```ts
const client = new TorClient();
const resultPath = await client.download('', {
filename: 'myfile.png',
dir: './downloads' // folder must exists!
});
console.log(resultPath); // string
```
#### Passing options for requests
You can pass your custom headers and request timeout.
```ts
const client = new TorClient();
const result = await client.get('https://www.deviceinfo.me/', {
headers: {
'User-Agent': 'Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/95.0.4638.69 Safari/537.36',
},
timeout: 20000,
});
console.log(result.data);
```
By default TorClient uses User-Agent: `Mozilla/5.0 (Windows NT 10.0; rv:109.0) Gecko/20100101 Firefox/115.0` (from Tor Browser - most popular Tor client).
## License
Distributed under the MIT License. See `LICENSE` for more information.