Programmable proxy

////////////////////////////////////////////////////////////////////////////////
// NO NEED TO READ ANYTHING BELOW IF YOU ARE NOT GOING TO CUSTOMIZE THE PROXY //
////////////////////////////////////////////////////////////////////////////////

You can also use socratex as a programmable proxy to meet your own needs.

$ npm i -s socratex

Socratex is an ES6 module, so you can use it in your modern Node.js projects.

import { Socratex } from 'socratex';

const [port, address, options] = ['4698', '': {}];

const socratex = new Socratex(options);

socratex.listen(port, address, async () => {
    console.log('TCP-Proxy-Server started at: ', server.address());
});

Options object use to customize the proxy

options should be an object.

upstream, tcpOutgoingAddress, injectData & injectResponse options

The options are functions having follow parameters:

• upstream-Function need to return/resolve a String with format -> IP:PORT or USER:PWD@IP:PORT of used http-proxy. If 'localhost' is returned/resolved, then the host-self will be used as proxy.
• tcpOutgoingAddress-Function need to return a String with format -> IP.
• injectData-Function need to return a String or buffer for the new spoofed data. This will be upstreamed as request.
• injectResponse-Function need to return a String or buffer for the new received data.

Note: These functions will be executed before first tcp-socket-connection is established.

Upstream to other proxies

If you don't want to use the host of active instance self, then you need to upstream connections to another http-proxy. This can be done with upstream attribute.

const options = {
    upstream: async () => { return 'x.x.x.x:3128'; },
};

The Basic Authorization mechanism

This activate basic authorization mechanism. The Auth-function will be executed while handling Proxy-Authentications.

Note: It needs to return True/False or a Promise that resolves to boolean (isAuthenticated).

const options = {
    basicAuth: async (user, password) => user === 'bar' && password === 'foo';
};

The Token Authorization mechanism

This activate token authorization mechanism. The Auth-function will be executed while handling Proxy-Authentications.

Note: It needs to return True/False or a Promise that resolves to boolean (isAuthenticated).

const options = {
    tokenAuth: async (token) => token === 'a-very-long-token';
};

Interception

This feature is in very early stage, and it's for web development only. The callbacks injectData & injectResponse could be used to intercept/spoof communication. These functions are executed with the data and session arguments.

Intercepting HTTPS

The boolean attribute intercept allows to break SSL-Communication between Source & Destination. This will activate Security-Alarm by most used browsers.

const [uaToSwitch, switchWith] = ['curl 7.79.1', 'a-fake-user-agent'];
const options = {
    intercept: true,
    injectData(data, session) {
        if (session.isHttps && data.toString().match(uaToSwitch)) {
            return Buffer.from(data.toString().replace(uaToSwitch, switchWith));
        }
        return data;
    },
};

curl -x localhost:8080 -k http://ifconfig.io/ua
curl 7.79.1

curl -x localhost:8080 -k https://ifconfig.me/ua
a-fake-user-agent

The keys Function

You can use this option to provide your own self-signed certificate.

If activated needs to return an Object {key:'String', cert:'String'} like native tls_connect_options.key & tls_connect_options.cert or false statement.

If no object is returned, then default keys will be used to update communication.

Note: This function will be executed before TLS-Handshake.

Session-instance

The Session-instance is a Object containing info/data about Tunnel.

Use .getConnections() to get the current connections.

setInterval(() => {
    const connections = socratex.getConnections();
    console.log([new Date()], 'OPEN =>', Object.keys(connections).length)
}, 3000);

The connection items in the connections array include useful attributes/methods:

• isHttps - Is session encrypted.
• getTunnelStats() - Get Stats for this tunnel
• getId() - Get Own ID-Session
• isAuthenticated() - Is the session authenticated by user or not.
• ... (More APIS tobe documented)

Dynamically routing

This example upstreams only requests for ifconfig.me to another proxy, for all other requests will be used localhost.

const options = {
    upstream(data, session) {
        return data.toString().includes('ifconfig.me')
            ? 'x.x.x.x:3128' : 'localhost';
    },
});

Testing with curl:

curl -x 127.0.0.1:8080 https://ifconfig.me
x.x.x.x

curl -x 127.0.0.1:8080 https://ifconfig.co
y.y.y.y