tor-ctrl
Version:
Node.js library for accessing the Tor control port
188 lines (185 loc) • 6.4 kB
TypeScript
type Result = {
code: number;
message: string;
};
type ResultList = Result[];
interface TorControlConfig {
host: string;
port: number;
password: string | undefined;
socketPath: string | undefined;
cookiePath: string | undefined;
}
/**
* @link https://spec.torproject.org/control-spec/commands.html?highlight=SIGNAL#signal
*/
type Signal = 'RELOAD' | 'SHUTDOWN' | 'DUMP' | 'DEBUG' | 'HALT' | 'HUP' | 'INT' | 'USR1' | 'USR2' | 'TERM' | 'NEWNYM' | 'CLEARDNSCACHE' | 'HEARTBEAT' | 'ACTIVE' | 'DORMANT';
declare class TorControl implements Disposable {
#private;
/**
* Get the current connection state of the TorControl
*/
get state(): "connected" | "disconnected";
constructor(config?: Partial<TorControlConfig>);
/**
* Establish a connection to the TorControl
*/
connect(): Promise<void>;
/**
* Close the connection to the TorControl
*/
disconnect(): Promise<void>;
/**
* Dispose the connection to the TorControl
*
* This method is called when the `using` statement is used on an instance of the class.
*
* Example:
* ```typescript
* using tor = new TorControl();
* await tor.connect();
* // ...
* ```
*/
[Symbol.dispose](): void;
/**
* Send a command to the TorControl
*
* Example:
* ```typescript
* const data = await torControl.sendCommand(['GETINFO', 'version']);
* console.log('GETINFO:', data); // { code: 250, message: 'version=...' }
* ```
*
* @link https://spec.torproject.org/control-spec/commands.html
* @param command
*/
sendCommand(command: string | string[]): Promise<ResultList>;
/**
* Authenticate
*
* **NOTE:** Authentication is automatically done when the connection is established.
*
* @link https://spec.torproject.org/control-spec/commands.html?highlight=AUTHENTICATE#authenticate
* @param password
*/
authenticate(password: string): Promise<Result>;
/**
* Authenticate using the cookie file
*
* This method reads the specified cookie file, converts its contents to a hexadecimal string,
* and then sends an AUTHENTICATE command to the Tor control port using the cookie.
*
* @link https://spec.torproject.org/control-spec/commands.html?highlight=AUTHENTICATE#authenticate
* @param {string} cookiePath - The path to the cookie file used for authentication.
*/
authenticateCookieFile(cookiePath: string): Promise<Result>;
/**
* Quit
*
* @link https://spec.torproject.org/control-spec/commands.html?highlight=QUIT#quit
*/
quit(): Promise<Result>;
/**
* Example:
*
* ```typescript
* const socksPort = await torControl.getConfig('SocksPort');
* if (socksPort) {
* console.log('SocksPort:', socksPort); // SocksPort: 9050
* }
* ```
*
* @link https://spec.torproject.org/control-spec/commands.html?highlight=GETCONF#getconf
* @param key
*/
getConfig(key: string): Promise<string>;
/**
* @link https://spec.torproject.org/control-spec/commands.html?highlight=SETCONF#setconf
* @param key
* @param value
*/
setConfig(key: string, value: string): Promise<Result>;
/**
* @link https://spec.torproject.org/control-spec/commands.html?highlight=RESETCONF#resetconf
* @param key
*/
resetConfig(key: string): Promise<Result>;
signal(signal: Signal | string): Promise<ResultList>;
signalReload(): Promise<Result>;
signalShutdown(): Promise<Result>;
signalDump(): Promise<Result>;
signalDebug(): Promise<Result>;
signalHalt(): Promise<Result>;
signalTerm(): Promise<Result>;
signalNewNym(): Promise<Result>;
signalClearDnsCache(): Promise<Result>;
signalUsr1(): Promise<Result>;
signalUsr2(): Promise<Result>;
/**
* Example:
*
* ```typescript
* const version = await torControl.getInfo('version');
* if (version) {
* console.log('Version:', version); // Version: Tor
* }
* ```
*
* @link https://spec.torproject.org/control-spec/commands.html?highlight=GETINFO#getinfo
* @param key
*/
getInfo(key: string): Promise<Result>;
/**
* Example:
*
* ```typescript
* const mar = await torControl.mapAddress('1.2.3.4', 'torproject.org');
* console.log('MAPADDRESS:', mar); // { code: 250, message: '1.2.3.4=torproject.org' }
*
* const gir = await torControl.getInfo('address-mappings/control');
* console.log('GETINFO:', gir); // { code: 250, message: 'address-mappings/control=1.2.3.4 torproject.org NEVER' }
* ```
*
* @link https://spec.torproject.org/control-spec/commands.html?highlight=MAPADDRESS#mapaddress
* @param address
* @param target
*/
mapAddress(address: string, target: string): Promise<Result>;
extendCircuit(circuitId: string): Promise<Result>;
/**
* @link https://spec.torproject.org/control-spec/commands.html?highlight=SETCIRCUITPURPOSE#setcircuitpurpose
* @param circuitId
* @param purpose
*/
setCircuitPurpose(circuitId: string, purpose: string): Promise<Result>;
/**
* @link https://spec.torproject.org/control-spec/commands.html?highlight=SETROUTERPURPOSE#setrouterpurpose
* @param nicknameOrKey
* @param purpose
*/
setRouterPurpose(nicknameOrKey: string, purpose: string): Promise<Result>;
/**
* @link https://spec.torproject.org/control-spec/commands.html?highlight=CLOSESTREAM#closestream
* @param streamId
* @param reason
*/
setStream(streamId: string, reason: string): Promise<Result>;
/**
* @link https://spec.torproject.org/control-spec/commands.html?highlight=CLOSECIRCUIT#closecircuit
* @param circuitId
*/
closeCircuit(circuitId: string): Promise<Result>;
/**
* @link https://spec.torproject.org/control-spec/commands.html?highlight=ATTACHSTREAM#attachstream
* @param streamId
* @param circuitId
* @param hop
*/
attachStream(streamId: string, circuitId: string, hop: number | undefined): Promise<Result>;
/**
* Alias for `signalNewNym`
*/
getNewIdentity(): Promise<Result>;
}
export { type Result, type ResultList, type Signal, TorControl, type TorControlConfig };