0ct0pu5
/
tor-router


			
							123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494
							<!DOCTYPE html>
<html lang="en">
<head>
    
    <meta charset="utf-8">
    <title>TorProcess.js - Documentation</title>
    
    
    <script src="scripts/prettify/prettify.js"></script>
    <script src="scripts/prettify/lang-css.js"></script>
    <!--[if lt IE 9]>
      <script src="//html5shiv.googlecode.com/svn/trunk/html5.js"></script>
    <![endif]-->
    <link type="text/css" rel="stylesheet" href="styles/prettify.css">
    <link type="text/css" rel="stylesheet" href="styles/jsdoc.css">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
</head>
<body>

<input type="checkbox" id="nav-trigger" class="nav-trigger" />
<label for="nav-trigger" class="navicon-button x">
  <div class="navicon"></div>
</label>

<label for="nav-trigger" class="overlay"></label>

<nav>
    
    <h2><a href="index.html">Home</a></h2><h3>Classes</h3><ul><li><a href="ControlServer.html">ControlServer</a><ul class='methods'><li data-type='method'><a href="ControlServer.html#.instance_info">instance_info</a></li><li data-type='method'><a href="ControlServer.html#close">close</a></li><li data-type='method'><a href="ControlServer.html#createDNSServer">createDNSServer</a></li><li data-type='method'><a href="ControlServer.html#createHTTPServer">createHTTPServer</a></li><li data-type='method'><a href="ControlServer.html#createSOCKSServer">createSOCKSServer</a></li><li data-type='method'><a href="ControlServer.html#createTorPool">createTorPool</a></li><li data-type='method'><a href="ControlServer.html#listen">listen</a></li><li data-type='method'><a href="ControlServer.html#listenTcp">listenTcp</a></li><li data-type='method'><a href="ControlServer.html#listenWs">listenWs</a></li></ul></li><li><a href="DNSServer.html">DNSServer</a><ul class='methods'><li data-type='method'><a href="DNSServer.html#listen">listen</a></li></ul></li><li><a href="HTTPServer.html">HTTPServer</a><ul class='methods'><li data-type='method'><a href="HTTPServer.html#listen">listen</a></li></ul></li><li><a href="SOCKSServer.html">SOCKSServer</a><ul class='methods'><li data-type='method'><a href="SOCKSServer.html#listen">listen</a></li></ul></li><li><a href="TorPool.html">TorPool</a><ul class='methods'><li data-type='method'><a href="TorPool.html#add">add</a></li><li data-type='method'><a href="TorPool.html#add_instance_to_group">add_instance_to_group</a></li><li data-type='method'><a href="TorPool.html#add_instance_to_group_at">add_instance_to_group_at</a></li><li data-type='method'><a href="TorPool.html#add_instance_to_group_by_name">add_instance_to_group_by_name</a></li><li data-type='method'><a href="TorPool.html#create">create</a></li><li data-type='method'><a href="TorPool.html#create_instance">create_instance</a></li><li data-type='method'><a href="TorPool.html#exit">exit</a></li><li data-type='method'><a href="TorPool.html#get_config_at">get_config_at</a></li><li data-type='method'><a href="TorPool.html#get_config_by_name">get_config_by_name</a></li><li data-type='method'><a href="TorPool.html#instance_at">instance_at</a></li><li data-type='method'><a href="TorPool.html#instance_by_name">instance_by_name</a></li><li data-type='method'><a href="TorPool.html#instances_by_group">instances_by_group</a></li><li data-type='method'><a href="TorPool.html#new_identites">new_identites</a></li><li data-type='method'><a href="TorPool.html#new_identites_by_group">new_identites_by_group</a></li><li data-type='method'><a href="TorPool.html#new_identity_at">new_identity_at</a></li><li data-type='method'><a href="TorPool.html#new_identity_by_name">new_identity_by_name</a></li><li data-type='method'><a href="TorPool.html#next">next</a></li><li data-type='method'><a href="TorPool.html#next_by_group">next_by_group</a></li><li data-type='method'><a href="TorPool.html#remove">remove</a></li><li data-type='method'><a href="TorPool.html#remove_at">remove_at</a></li><li data-type='method'><a href="TorPool.html#remove_by_name">remove_by_name</a></li><li data-type='method'><a href="TorPool.html#remove_instance_from_group">remove_instance_from_group</a></li><li data-type='method'><a href="TorPool.html#remove_instance_from_group_at">remove_instance_from_group_at</a></li><li data-type='method'><a href="TorPool.html#remove_instance_from_group_by_name">remove_instance_from_group_by_name</a></li><li data-type='method'><a href="TorPool.html#set_config_all">set_config_all</a></li><li data-type='method'><a href="TorPool.html#set_config_at">set_config_at</a></li><li data-type='method'><a href="TorPool.html#set_config_by_group">set_config_by_group</a></li><li data-type='method'><a href="TorPool.html#set_config_by_name">set_config_by_name</a></li><li data-type='method'><a href="TorPool.html#signal_all">signal_all</a></li><li data-type='method'><a href="TorPool.html#signal_at">signal_at</a></li><li data-type='method'><a href="TorPool.html#signal_by_group">signal_by_group</a></li><li data-type='method'><a href="TorPool.html#signal_by_name">signal_by_name</a></li></ul></li><li><a href="TorProcess.html">TorProcess</a><ul class='methods'><li data-type='method'><a href="TorProcess.html#create">create</a></li><li data-type='method'><a href="TorProcess.html#exit">exit</a></li><li data-type='method'><a href="TorProcess.html#get_config">get_config</a></li><li data-type='method'><a href="TorProcess.html#new_identity">new_identity</a></li><li data-type='method'><a href="TorProcess.html#set_config">set_config</a></li><li data-type='method'><a href="TorProcess.html#signal">signal</a></li></ul></li></ul><h3>Modules</h3><ul><li><a href="module-tor-router.html">tor-router</a></li><li><a href="module-tor-router_ControlServer.html">tor-router/ControlServer</a></li><li><a href="module-tor-router_default_config.html">tor-router/default_config</a></li><li><a href="module-tor-router_default_ports.html">tor-router/default_ports</a></li><li><a href="module-tor-router_DNSServer.html">tor-router/DNSServer</a></li><li><a href="module-tor-router_HTTPServer.html">tor-router/HTTPServer</a></li><li><a href="module-tor-router_launch.html">tor-router/launch</a></li><li><a href="module-tor-router_nconf_load_env.html">tor-router/nconf_load_env</a></li><li><a href="module-tor-router_SOCKSServer.html">tor-router/SOCKSServer</a></li><li><a href="module-tor-router_TorPool.html">tor-router/TorPool</a></li><li><a href="module-tor-router_TorProcess.html">tor-router/TorProcess</a></li><li><a href="module-tor-router_winston_silent_logger.html">tor-router/winston_silent_logger</a></li></ul><h3>Events</h3><ul><li><a href="DNSServer.html#event:instance-connection">instance-connection</a></li><li><a href="HTTPServer.html#event:instance-connection">instance-connection</a></li><li><a href="SOCKSServer.html#event:instance-connection">instance-connection</a></li><li><a href="TorPool.html#event:instance_created">instance_created</a></li><li><a href="TorProcess.html#event:control_listen">control_listen</a></li><li><a href="TorProcess.html#event:controller_ready">controller_ready</a></li><li><a href="TorProcess.html#event:dns_listen">dns_listen</a></li><li><a href="TorProcess.html#event:error">error</a></li><li><a href="TorProcess.html#event:process_exit">process_exit</a></li><li><a href="TorProcess.html#event:ready">ready</a></li><li><a href="TorProcess.html#event:socks_listen">socks_listen</a></li></ul><h3>Global</h3><ul><li><a href="global.html#assembleHost">assembleHost</a></li><li><a href="global.html#cleanUp">cleanUp</a></li><li><a href="global.html#env_whitelist">env_whitelist</a></li><li><a href="global.html#logger">logger</a></li><li><a href="global.html#main">main</a></li><li><a href="global.html#nconf">nconf</a></li><li><a href="global.html#REALM">REALM</a></li><li><a href="global.html#setup_nconf_env">setup_nconf_env</a></li><li><a href="global.html#TOR_ROUTER_PROXY_AGENT">TOR_ROUTER_PROXY_AGENT</a></li></ul>
</nav>

<div id="main">
    
    <h1 class="page-title">TorProcess.js</h1>
    

    <section>
        <article>
            <pre class="prettyprint source linenums"><code>const spawn = require('child_process').spawn;
const fs = require('fs');

const crypto = require('crypto');
const { connect } = require('net');
const os = require('os');

const Promise = require('bluebird');	
const _ = require('lodash');
const { EventEmitter } = require('eventemitter3');
const shell = require('shelljs');

const getPort = require('get-port');
const del = require('del');
const temp = require('temp');
const { TorController } = require('@deadcanaries/granax');
const nanoid = require("nanoid");
const winston = require('winston');
Promise.promisifyAll(temp);
Promise.promisifyAll(fs);

temp.track();

/**
 * @typedef {Object} InstanceDefinition
 * @property {string} [Name] - Name of the instance.
 * @property {string[]|string} [Group=[]] - Groups the instance belongs to.
 * @property {Object} [Config={}] - Configuration that will be passed to Tor. See {@link https://bit.ly/2QrmI3o|Tor Documentation} for all possible options.
 * @property {Number} [Weight] - Weight of the instance for "weighted" load balancing.
 */

/**
 * Class that represents an individual Tor process.
 * 
 * @extends EventEmitter
 */
class TorProcess extends EventEmitter {
	/**
	 * Creates an instance of `TorProcess`
	 * 
	 * @param {string} tor_path - Path to the Tor executable.
	 * @param {InstanceDefinition} [definition] - Object containing various options for the instance. See {@link InstanceDefinition} for more info.
	 * @param {Object} [granax_options] - Object containing options that will be passed to granax.
	 * @param {Logger} [logger] - A winston logger. If not provided no logging will occur.
	 */
	constructor(tor_path, definition, granax_options, logger) {
		super();
		this.logger = logger || require('./winston_silent_logger');

		definition = definition || {};
		definition.Group = definition.Group ? [].concat(definition.Group) : [];
		definition.Config = definition.Config || {};

		this._definition = definition;

		/**
		 * Path to the Tor executable.
		 * 
		 * @type {string}
		 * @public  
		 */
		this.tor_path = tor_path;
 
		/**
		 * Object containing options that will be passed to granax.
		 * 
		 * @type {Object}
		 * @public  
		 */
		this.granax_options = granax_options;
 
		/**
		 * The password that will be set for the control protocol.
		 * 
		 * @type {string}
		 * @public  
		 */		
		this.control_password = crypto.randomBytes(128).toString('base64');
		this._id = nanoid(12);

		this.tor_config.DataDirectory = this.tor_config.DataDirectory || temp.mkdirSync();
	}

	/**
	 * Kills the Tor process.
	 * 
	 * @async
	 * @returns {Promise}
	 */
	async exit() {
		let p = new Promise((resolve, reject) => {
			this.once('process_exit', (code) => {
				resolve();
			});
		});

		this.process.kill('SIGINT');
		
		await p;
	}

	/**
	 * The unique identifier assigned to each instance.
	 * 
	 * @readonly
	 * @type {string}
	 */
	get id() { return this._id; }

	/**
	 * Groups the instance are currently in.
	 * 
	 * @readonly
	 * @type {string[]}
	 */
	get instance_group() {
		return (this.definition &amp;&amp; this.definition.Group);
	}

	/**
	 * Either the "Name" property of the definition or the {@link TorProcess#id} property.
	 * 
	 * @readonly
	 * @type {string}
	 */
	get instance_name() {
		return (this.definition &amp;&amp; this.definition.Name) || this.id;
	}

	/**
	 * The definition used to create the instance.
	 * 
	 * @readonly
	 * @type {string}
	 */
	get definition() { return this._definition; }

	/**
	 * The configuration passed to Tor. The same value as `definition.Config`.
	 * 
	 * @readonly
	 * @type {Object}
	 */
	get tor_config() { return this.definition.Config; }

	/**
	 * Port Tor is bound to for DNS traffic.
	 * 
	 * @readonly
	 * @type {number}
	 */
	get dns_port() {
		return this._ports.dns_port;
	}

	/**
	 * Port Tor is bound to for SOCKS5 traffic.
	 * 
	 * @readonly
	 * @type {number}
	 */
	get socks_port() {
		return this._ports.socks_port;
	}

	/**
	 * Port Tor is bound to for API access.
	 * 
	 * @readonly
	 * @type {number}
	 */
	get control_port() {
		return this._ports.control_port;
	}

	/**
	 * Instance of granax.TorController connected to the Tor process.
	 * 
	 * @readonly
	 * @type {TorController}
	 */
	get controller() {
		return this._controller;
	}

	/**
	 * Property identifiyng whether Tor has started.
	 * 
	 * @readonly
	 * @type {boolean}
	 */
	get ready() { return this._ready; }

	/* Passthrough to granax */

	/**
	 * Requests a new identity via the control protocol.
	 * 
	 * @async
	 */
	async new_identity() {
		this.logger.info(`[tor-${this.instance_name}]: requested a new identity`);
		
		await this.controller.cleanCircuitsAsync();
	}

	/**
	 * Retrieves a configuration value from the instance via the control protocol.
	 * 
	 * @async
	 * @throws Will throw an error if not connected to the control protocol.
	 * @param {string} keyword - The name of the configuration property to retrieve.
	 * 
	 * @returns {Promise&lt;string[]>}
	 */
	async get_config(keyword) {
		if (!this.controller)
			throw new Error(`Controller is not connected`);

		return await this.controller.getConfigAsync(keyword);
	}

	/**
	 * Sets a configuration value for the instance via the control protocol.
	 * 
	 * @async
	 * @throws Will throw an error if not connected to the control protocol.
	 * @param {string} keyword - The name of the configuration property to retrieve.
	 * @param {any} value - Value to set the property to.
	 * 
	 * @returns {Promise}
	 */
	async set_config(keyword, value) {
		if (!this.controller) {
			return new Error(`Controller is not connected`);
		}

		return await this.controller.setConfigAsync(keyword, value);
	}

	/**
	 * Sends a signal via the control tnterface.
	 * 
	 * @async
	 * @throws Will throw an error if not connected to the control protocol.
	 * @param {string} signal - The signal to send.
	 * 
	 * @returns {Promise}
	 */
	async signal(signal) {
		if (!this.controller) {
			throw new Error(`Controller is not connected`);
		}

		return await this.controller.signal(signal);
	}

	/**
	 * Creates the Tor process based on the configuration provided. Promise is resolved when the process has been started.
	 * 
	 * @async
	 * 
	 * @returns {Promise&lt;ChildProcess>} - The process that has been created.
	 */
	async create() {
		this._ports = {};
		let dnsPort = this._ports.dns_port = await getPort();
		let socksPort = this._ports.socks_port =  await getPort();
		let controlPort = this._ports.control_port = await getPort();
		Object.freeze(this._ports);

		let options = {
			DNSPort: `127.0.0.1:${dnsPort}`,
			SocksPort: `127.0.0.1:${socksPort}`,
			ControlPort: `127.0.0.1:${controlPort}`,
			HashedControlPassword: shell.exec(`${this.tor_path} --quiet --hash-password "${this.control_password}"`, { async: false, silent: true }).stdout.trim()
		};

		let config = _.extend(_.cloneDeep(this.tor_config), options);
		let text = Object.keys(config).map((key) => `${key} ${config[key]}`).join(os.EOL);

		let configFile = await temp.openAsync('tor-router');
		let configPath = configFile.path;
		await fs.writeFileAsync(configPath, text);

		let tor = spawn(this.tor_path, ['-f', configPath], {
			stdio: ['ignore', 'pipe', 'pipe'],
			detached: false
		});

		tor.on('close', (async (code) => {
			if (this.definition &amp;&amp; !this.definition.Name) {
				await del(this.tor_config.DataDirectory, { force: true });
			}
			
			/**
			 * An event that fires when the process has closed.
			 * 
			 * @event TorProcess#process_exit
			 * @type {number}
			 * @param {number} code - The exit code from the process.
			 */
			this.emit('process_exit', code);
		}));

		tor.stderr.on('data', (data) => {
			let error_message = Buffer.from(data).toString('utf8');
			this.emit('error', new Error(error_message));
		});

		this.once('ready', () => {
			this._ready = true;

			this.logger.info(`[tor-${this.instance_name}]: tor is ready`);
		});

		this.on('control_listen', (async () => {
			try {
				let socket = connect(this.control_port);
				socket.on('error', ((error) => {
					this.logger.error(`[tor-${this.instance_name}]: ${error.stack}`);
					this.emit('error', error);
				}));
				this._controller = new TorController(socket, _.extend({ authOnConnect: false }, this.granax_options));
				Promise.promisifyAll(this._controller);
				this.controller.on('ready', () => {
					this.logger.debug(`[tor-${this.instance_name}]: connected via the tor control protocol`);
					this.controller.authenticate(`"${this.control_password}"`, (err) => {
						if (err) {
							this.logger.error(`[tor-${this.instance_name}]: ${err.stack}`);
							this.emit('error', err);
						} else {
							this.logger.debug(`[tor-${this.instance_name}]: authenticated with tor instance via the control protocol`);
							/** 
							 * Is true when the connected via the control protcol
							 * @type {boolean}
							 */
							this.control_port_connected = true;
							/**
							 * An event that fires when a connection has been established to the control protocol.
							 * 
							 * @event TorProcess#controller_ready
							 */
							this.emit('controller_ready');
						}
					});
				});
			} catch (error) {
				this.logger.error(`[tor-${this.instance_name}]: ${err.stack}`);
				this.emit('error', err);
			}
		}));

		tor.stdout.on('data', (data) => {
			let text = Buffer.from(data).toString('utf8');
			let msg = text.indexOf('] ') !== -1 ? text.split('] ').pop() : null;
			if (text.indexOf('Bootstrapped 100%: Done') !== -1){
				this.bootstrapped = true;
				/**
				 * An event that fires when the Tor process is fully bootstrapped (and ready for traffic).
				 * 
				 * @event TorProcess#ready
				 */
				this.emit('ready');
			}

			if (text.indexOf('Opening Control listener on') !== -1) {
				this.control_port_listening = true;
				/**
				 * An event that fires when the Tor process has started listening for control interface traffic.
				 * 
				 * @event TorProcess#control_listen
				 */
				this.emit('control_listen');
			}

			if (text.indexOf('Opening Socks listener on') !== -1) {
				this.socks_port_listening = true;
				/**
				 * An event that fires when the Tor process has started listening for SOCKS5 traffic.
				 * 
				 * @event TorProcess#socks_listen
				 */
				this.emit('socks_listen');
			}

			if (text.indexOf('Opening DNS listener on') !== -1) {
				this.dns_port_listening = true;
				/**
				 * An event that fires when the Tor process has started listening for DNS traffic.
				 * 
				 * @event TorProcess#dns_listen
				 */
				this.emit('dns_listen');
			}

			if (text.indexOf('[err]') !== -1) {
				/**
				 * An event that fires when the Tor process has written an error to stdout, stderr or when an error occurs connecting via the control protocol.
				 * 
				 * @event TorProcess#error
				 * @type {Error}
				 * @returns {Error}
				 */
				this.emit('error', new Error(msg));
				this.logger.error(`[tor-${this.instance_name}]: ${msg}`);
			}

			else if (text.indexOf('[notice]') !== -1) {
				this.logger.debug(`[tor-${this.instance_name}]: ${msg}`);
			}

			else if (text.indexOf('[warn]') !== -1) {
				this.logger.warn(`[tor-${this.instance_name}]: ${msg}`);
			}
		});

		this.process = tor;
		
		return tor;
	}
};

/**
 * Module that contains the {@link TorProcess} class.
 * @module tor-router/TorProcess
 * @see TorProcess
 */
module.exports = TorProcess;</code></pre>
        </article>
    </section>


</div>

<br class="clear">

<footer>
    Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 3.5.5</a> on Tue Sep 25 2018 12:53:23 GMT-0400 (Eastern Daylight Time) using the <a href="https://github.com/clenemt/docdash">docdash</a> theme.
</footer>

<script>prettyPrint();</script>
<script src="scripts/linenumber.js"></script>


</body>
</html>