react-native-nitro-tor

A Tor Daemon and Onion Routing Client for React Native using pure C++ NitroModules.

Features

• Run a Tor daemon directly in your React Native application
• Create and manage Tor hidden services
• Make HTTP requests over the Tor network (GET, POST, PUT, DELETE)
• Built with performance in mind using React Native's NitroModules
• Cross-platform support for Android, iOS and macOS

Installation

1# Using npm
2npm install react-native-nitro-tor
3
4# Using yarn
5yarn add react-native-nitro-tor

You'll also need to install the dependency:

1npm install react-native-nitro-modules
2# or
3yarn add react-native-nitro-modules

Platform Support

Platform	Support
iOS	✅
macOS	✅
Android	✅ (arm64-v8a, x86_64, x86)

Usage

Basic Example

1import { RnTor } from 'react-native-nitro-tor';
2
3// Start Tor with a hidden service
4const startTor = async () => {
5  const result = await RnTor.startTorIfNotRunning({
6    data_dir: '/path/to/tor/data',
7    socks_port: 9050,
8    target_port: 8080,
9    timeout_ms: 60000,
10  });
11
12  if (result.is_success) {
13    console.log(`Tor started successfully!`);
14    console.log(`Onion address: ${result.onion_address}`);
15    console.log(`Control: ${result.control}`);
16  } else {
17    console.error(`Failed to start Tor: ${result.error_message}`);
18  }
19};
20
21// Shut down the Tor service
22const shutdown = async () => {
23  const result = await RnTor.shutdownService();
24  console.log(`Tor shutdown ${result ? 'successful' : 'failed'}`);
25};

HTTP Methods Over Tor

1import { RnTor } from 'react-native-nitro-tor';
2
3// Make an HTTP GET request through Tor
4const makeGetRequest = async () => {
5  const result = await RnTor.httpGet({
6    url: 'http://example.com',
7    headers: '',
8    timeout_ms: 2000,
9  });
10  console.log(`Status code: ${result.status_code}`);
11  console.log(`Response body: ${result.body}`);
12  if (result.error) {
13    console.error(`Error: ${result.error}`);
14  }
15};
16
17// Make an HTTP POST request through Tor
18const makePostRequest = async () => {
19  const result = await RnTor.httpPost({
20    url: 'http://httpbin.org/post',
21    body: '{"test":"data"}',
22    headers: '{"Content-Type":"application/json"}',
23    timeout_ms: 2000,
24  });
25  console.log(`Status code: ${result.status_code}`);
26  console.log(`Response body: ${result.body}`);
27  if (result.error) {
28    console.error(`Error: ${result.error}`);
29  }
30};
31
32// Make an HTTP PUT request through Tor
33const makePutRequest = async () => {
34  const result = await RnTor.httpPut({
35    url: 'http://httpbin.org/put',
36    body: '{"updated":"value"}',
37    headers: '{"Content-Type":"application/json"}',
38    timeout_ms: 2000,
39  });
40  console.log(`Status code: ${result.status_code}`);
41  console.log(`Response body: ${result.body}`);
42  if (result.error) {
43    console.error(`Error: ${result.error}`);
44  }
45};
46
47// Make an HTTP DELETE request through Tor
48const makeDeleteRequest = async () => {
49  const result = await RnTor.httpDelete({
50    url: 'http://httpbin.org/delete',
51    headers: '{"Content-Type":"application/json"}',
52    timeout_ms: 2000,
53  });
54  console.log(`Status code: ${result.status_code}`);
55  console.log(`Response body: ${result.body}`);
56  if (result.error) {
57    console.error(`Error: ${result.error}`);
58  }
59};

Advanced Usage

1import { RnTor } from 'react-native-nitro-tor';
2
3// Initialize Tor service
4const initTor = async () => {
5  const initialized = await RnTor.initTorService({
6    socks_port: 9050,
7    data_dir: '/path/to/tor/data',
8    timeout_ms: 60000,
9  });
10
11  if (initialized) {
12    console.log('Tor service initialized successfully');
13    return true;
14  }
15  return false;
16};
17
18// Create a hidden service
19const createService = async () => {
20  const serviceResult = await RnTor.createHiddenService({
21    port: 9055,
22    target_port: 9056,
23    // Optionally provide key_data for persistent services
24  });
25
26  if (serviceResult.is_success) {
27    console.log(`Created hidden service at: ${serviceResult.onion_address}`);
28  }
29};
30
31// Get the current status of the Tor service.
32// 0: Tor is in the process of starting.
33// 1: Tor is running.
34// 2: Stopped/Not running/error.
35
36// Check service status
37const checkStatus = async () => {
38  const status = await RnTor.getServiceStatus();
39  console.log(`Current Tor service status: ${status}`);
40};
41
42// Shutdown Tor service
43const shutdown = async () => {
44  const result = await RnTor.shutdownService();
45  console.log(`Tor shutdown ${result ? 'successful' : 'failed'}`);
46};

API Reference

Types

1type ByteArray64 = number[];
2
3interface TorConfig {
4  socks_port: number;
5  data_dir: string;
6  timeout_ms: number;
7}
8
9interface HiddenServiceParams {
10  port: number;
11  target_port: number;
12  key_data?: ByteArray64;
13}
14
15interface StartTorParams {
16  data_dir: string;
17  key_data?: ByteArray64;
18  socks_port: number;
19  target_port: number;
20  timeout_ms: number;
21}
22
23interface StartTorResponse {
24  is_success: boolean;
25  onion_address: string;
26  control: string;
27  error_message: string;
28}
29
30interface HiddenServiceResponse {
31  is_success: boolean;
32  onion_address: string;
33  control: string;
34}
35
36interface HttpGetParams {
37  url: string;
38  headers: string;
39  timeout_ms: number;
40}
41
42interface HttpPostParams {
43  url: string;
44  body: string;
45  headers: string;
46  timeout_ms: number;
47}
48
49interface HttpPutParams {
50  url: string;
51  body: string;
52  headers: string;
53  timeout_ms: number;
54}
55
56interface HttpDeleteParams {
57  url: string;
58  headers: string;
59  timeout_ms: number;
60}
61
62interface HttpResponse {
63  status_code: number;
64  body: string;
65  error: string;
66}

Methods

• initTorService(config: TorConfig): Promise<boolean> Initialize the Tor service with the given configuration.

• createHiddenService(params: HiddenServiceParams): Promise<HiddenServiceResponse> Create a new Tor hidden service with the specified parameters.

• startTorIfNotRunning(params: StartTorParams): Promise<StartTorResponse> Start the Tor daemon with a hidden service if it's not already running. This is the recommended method for most use cases.

• getServiceStatus(): Promise<number> Get the current status of the Tor service. 0: Tor is in the process of starting. 1: Tor is running. 2: Stopped/Not running/error.

• deleteHiddenService(onionAddress: string): Promise<boolean> Delete an existing hidden service by its onion address.

• shutdownService(): Promise<boolean> Completely shut down the Tor service.

• httpGet(params: HttpGetParams): Promise<HttpResponse> Make an HTTP GET request through the Tor network.

• httpPost(params: HttpPostParams): Promise<HttpResponse> Make an HTTP POST request through the Tor network.

• httpPut(params: HttpPutParams): Promise<HttpResponse> Make an HTTP PUT request through the Tor network.

• httpDelete(params: HttpDeleteParams): Promise<HttpResponse> Make an HTTP DELETE request through the Tor network.

Binary Files

• iOS and MacOS: Binaries are located in the root of the project as Tor.xcframework
• Android: Binaries are located in android/src/main/jniLibs

Architecture Support

• Android: arm64-v8a, x86_64, x86

Running the example app

# Install dependencies
yarn install

# Generate native interfaces
yarn nitrogen

# Start metro
yarn example start

# For android
yarn example android

# For ios
yarn example ios

# IF ABOVE STEP FOR IOS THROWS ERRORS, you can also try:
cd example/ios && pod install

- Open the NitroTorExample.xcworkspace inside of xcode.
- Drag the Tor.xcframework from the root of the project to xcode project and select the "Copy files to destination" option.
- Build and run from inside of xcode.

License

MIT

Credits

This project builds upon the work of:

• react-native-tor
• sifir-rs-sdk
• libtor

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.