Example Domain

diff --git a/README.md b/README.md index 807628d..7fccba3 100644 --- a/README.md +++ b/README.md @@ -1,12 +1,40 @@ # Corrosion + Titanium Networks main web proxy. -Successor to [Alloy](https://github.com/titaniumnetwork-dev/alloy) -# Installation: +Successor to [Alloy](https://github.com/titaniumnetwork-dev/alloy). + +## Table of Contents +- [Corrosion](#corrosion) + - [Table of Contents](#table-of-contents) +- [Installation](#installation) +- [Basic Example](#basic-example) +- [Public Deployment Example](#public-deployment-example) + - [Initial Setup](#initial-setup) + - [Testing](#testing) + - [Persistence](#persistence) + - [PM2](#pm2) + - [systemd](#systemd) + - [Nginx Setup](#nginx-setup) + - [Letsencrypt](#letsencrypt) + - [Frontend Examples](#frontend-examples) +- [Advanced Configuration](#advanced-configuration) +- [Middleware](#middleware) + - [Default middleware](#default-middleware) + - [Available Middleware](#available-middleware) + - [address (Request)](#address-request) + - [blacklist](#blacklist) +- [Contributing](#contributing) + - [Needs Improvement](#needs-improvement) +- [Todo](#todo) + +# Installation + ``` npm i corrosion ``` -# Example: +# Basic Example + ```javascript const Corrosion = require('corrosion'); const proxy = new Corrosion(); @@ -18,148 +46,199 @@ http.createServer((req, res) => ).listen(80); ``` -Access a website by going to `/prefix/gateway?url=URL` +Access a website by going to `/prefix/gateway?url=URL`. Much more in depth one is in the [demo folder](demo/). -# API: - - -## Index -- `config` - - `prefix` String - URL Prefix - - `title` (Boolean / String) - Title used for HTML documents - - `ws` Boolean - WebSocket rewriting - - `cookie` Boolean - Request Cookies - - `codec` String - URL encoding (base64, plain, xor). - - `requestMiddleware` Array - Array of [middleware](#middleware) functions for proxy request (Server). - - `responseMiddleware` Array - Array of [middleware](#middleware) functions for proxy response (Server). - - `standardMiddleware` Boolean - Use the prebuilt [middleware](#middleware) used by default (Server). +# Public Deployment Example + +For implementing a Corrosion server into your production website, we recommend you follow the below configuration. + +## Initial Setup + +`index.html` + +```html + + + + + + + + + +``` + +`index.js` + +```javascript +// https here is necesary for some features to work, even if this is going to be behind an SSL-providing reverse proxy. +const https = require('https'); +const fs = require('fs'); +const path = require('path'); +const Corrosion = require('corrosion'); -#### request - - `request` Request - - `response` Response +// you are free to use self-signed certificates here, if you plan to route through an SSL-providing reverse proxy. +const ssl = { + key: fs.readFileSync(path.join(__dirname, '/ssl.key')), + cert: fs.readFileSync(path.join(__dirname, '/ssl.cert')), +}; +const server = https.createServer(ssl); +const proxy = new Corrosion({ + codec: 'xor', // apply basic xor encryption to url parameters in an effort to evade filters. Optional. + prefix: '/get/' // specify the endpoint (prefix). Optional. +}); -#### upgrade - - `request` Request - - `socket` Socket - - `head` Head +proxy.bundleScripts(); -#### bundleScripts -Bundles scripts for client injection. Important when updating proxy. +server.on('request', (request, response) => { + if (request.url.startsWith(proxy.prefix)) return proxy.request(request, response); + response.end(fs.readFileSync(__dirname + '/index.html', 'utf-8')); +}).on('upgrade', (clientRequest, clientSocket, clientHead) => proxy.upgrade(clientRequest, clientSocket, clientHead)).listen(8443); // port other than 443 if it is needed by other software. +``` -## Properties - - [url](#url) - - [html](#html) - - [js](#js) - - [css](#css) - - [cookies](#cookies) - - [config](#index) - - [codec](#codec) - - [prefix](#url) +In the same directory in which you saved the above files, generate some self-signed SSL certificates. +```shell-session +root@corrosion:~$ openssl req -x509 -newkey rsa:4096 -keyout ssl.key -out ssl.cert -days 365 +``` +## Testing -## url +Run the server to ensure everything is working. -#### wrap - - `val` String - - `config` Configuration - - `base` WHATWG URL - - `origin` Location origin - Adds a location origin before the proxy url - - `flags` Array - ['xhr'] => /service/xhr_/https%3A%2F%2Fexample.org/ +```shell-session +root@corrosion:~$ node index.js &; cpid=$! +root@corrosion:~$ curl -k "https://localhost:8443/get/hvtrs8%2F-ezaopne%2Ccmm" + + + Example Domain +... +user@corrosion:~$ kill $cpid +``` -#### unwrap - - `val` String - - `config` Configuration - - `origin` Location origin - Required if a location origin starts before the proxy url - - `flags` Boolean - Returns with both the URL and flags found { value: 'https://example.org', flags: ['xhr'], }) - - `leftovers` Boolean - Use any leftovers if any after the encoded proxy url +Now, you can setup this server to run as a service. Two popular options are PM2 (tailored for NodeJS applications) and systemd. +## Persistence -## Properties - - `regex` Regex used to determine to rewrite the URL or not. +### PM2 - - `prefix` URL Prefix +```shell-session +root@corrosion:~$ npm i pm2 -g +root@corrosion:~$ pm2 start index.js +root@corrosion:~$ pm2 startup +root@corrosion:~$ pm2 save +``` - - `codec` (base64, plain, xor) +### systemd +``` +[Unit] +Description=Corrosion +After=network-online.target +Wants=network-online.target systemd-networkd-wait-online.service -## js +StartLimitIntervalSec=500 +StartLimitBurst=5 -#### process - - `source` JS script - - `url` URL for heading +[Service] +Restart=on-failure +RestartSec=5s -#### iterate - - `ast` JS AST - - `Callback` Handler initated on AST node +WorkingDirectory=/root/corrosion/path/to/server +ExecStart=/usr/bin/env node index.js -#### createHead - - `url` URL for heading +[Install] +WantedBy=multi-user.target +``` -#### createCallExperssion - - `callee` Acorn.js Node - - `args` Array +Save the above in /lib/systemd/system/corrosion.service -#### createArrayExpression - - `elements` Array +```shell-session +root@corrosion:~$ chmod 644 /lib/systemd/system/corrosion.service +root@corrosion:~$ systemctl daemon-reload +root@corrosion:~$ systemctl start corrosion +root@corrosion:~$ systemctl enable corrosion +``` -#### createIdentifier - - `name` Identifier name - - `preventRewrite` Prevent further rewrites +## Nginx Setup -#### createLiteral - - `value` Literal value +Setup the Nginx reverse proxy to serve Corrosion and certbot to obtain Letsencrypt certificates. -## css +```shell-session +root@corrosion:~$ apt install -y nginx python3 python3-venv libaugeas0 +root@corrosion:~$ python3 -m venv /opt/certbot/ +root@corrosion:~$ /opt/certbot/bin/pip install --upgrade pip +root@corrosion:~$ /opt/certbot/bin/pip install certbot certbot-nginx +root@corrosion:~$ ln -s /opt/certbot/bin/certbot /usr/bin/certbot +``` -#### process - - `source` CSS - - `config` Configuration - - `base` WHATWG URL - - `origin` Location origin - - `context` CSS-Tree context +Now, create the following Nginx config in `/etc/nginx/sites-enabled/corrosion`. All of the header options are important and necesary. -## html +``` +server { + root /var/www/path/to/webroot; + server_name your.domain.com; + + location / { + proxy_set_header Accept-Encoding ""; + proxy_set_header X-Real-IP $remote_addr; + proxy_set_header X-Forwarded-Host $host:$server_port; + proxy_set_header X-Forwarded-Server $host; + proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; + proxy_set_header Upgrade $http_upgrade; + proxy_set_header Connection "Upgrade"; + proxy_pass https://127.0.0.1:8443; # the port it's listening on + proxy_http_version 1.1; + proxy_set_header Host $host; + } + + listen 80; +} +``` -#### process - - `source` HTML Source - - `config` Configuration - - `document` Determines of its a document or fragment for parsing - - `base` WHATWG URL - - `origin` Location origin +## Letsencrypt -#### source - - `processed` Rewritten HTML - - `config` Configuration - - `document` Determines of its a document or fragment for parsing +Finally, get our Letsencrypt certificates and restart nginx! -### Properties -- `map` Map for attribute rewriting +```shell-session +root@corrosion:~$ certbot --nginx -d +root@corrosion:~$ systemctl restart nginx +``` +Your site should be working now. If you want to add a custom frontend to make it usable, you should expand the index.js to serve your frontend. This can be easily integrated with Express and other NodeJS webserver frameworks. See some examples of proxy frontends that use Corrosion. -## cookies +## Frontend Examples -#### encode - - `input` New (Cookie / Cookies) - - `config` Configuration - - `url` WHATWG URL - - `domain` Cookie Domain - - `secure` Cookie Secure +[Holy Unblocker](https://github.com/titaniumnetwork-dev/Holy-Unblocker) -#### decode - - `store` Encoded Cookies - - `config` Configuration - - `url` WHATWG URL +[Vanadium](https://github.com/titaniumnetwork-dev/Vanadium) -## codec +[Reborn](https://github.com/titaniumnetwork-dev/Reborn) -#### encode -#### decode - - `str` String +# Advanced Configuration +```javascript +{ + 'prefix': '/get/', // String - URL Prefix + 'title': 'Woah Corrosion', // (Boolean / String) - Title used for HTML documents + 'ws': true, // Boolean - WebSocket rewriting + 'cookie': true, // Boolean - Request Cookies + 'codec': 'base64', // String - URL encoding (base64, plain, xor). + 'requestMiddleware': [Corrosion.middleware.address([0.0.0.0])] // Array - Array of [middleware](../README.md#middleware) functions for proxy request (Server). + 'responseMiddleware': [myCustomMiddleware()] // Array - Array of [middleware](../README.md#middleware) functions for proxy response (Server). + 'standardMiddleware': true // Boolean - Use the prebuilt [middleware](../README.md#middleware) used by default (Server). +} +``` -## middleware +# Middleware Middleware are functions that will be executed either before request or after response. These can alter the way a request is made or response is sent. @@ -195,7 +274,7 @@ function(ctx) {r ### Available Middleware #### address (Request) - - `arr` Array of IP addresses to use in request + - `arr` Array of IP addresses to use in request. ```javascript const Corrosion = require('corrosion'); @@ -209,9 +288,9 @@ const proxy = new Corrosion({ }); ``` -### blacklist - - `arr` Array of hostnames to block clients from seeing - - `page` Block page +#### blacklist + - `arr` Array of hostnames to block clients from seeing. + - `page` Block page. ```javascript const Corrosion = require('corrosion'); @@ -225,6 +304,18 @@ const proxy = new Corrosion({ }); ``` -# Todo: +# Contributing + +[API Documentation.](wiki/API) + +See something lacking in Corrosion that you can fix? Fork the repo, make some changes, and send in a pull request. + +## Needs Improvement + - Code readability/commenting + - Documentation (wiki) + - JS Rewriter + - Uniform error codes + +# Todo -- Inject header much more property in JS rewriter (because of import statements) +- JS Rewriter: Inject header properties (due to import statements).