corsproxy

Node.js server that is corsproxy.io API compatible… can be used as a self-hosted drop-in replacement.

• supports per-request header overrides via query parameters
• supports restricting access to requests that include an API key

Installation and Usage: Globally

How to: Install:

npm install --global "@warren-bank/corsproxy"

How to: Run the server(s):

corsproxy <options>

options:
========
--help
--version
--port <number>
--acl-ip <ip_address_list>
--api-keys <key_list>
--req-insecure
--tls
--tls-cert <filepath>
--tls-key <filepath>
--tls-pass <filepath>

Options:

• --port is the port number that the server listens on
  • ex: 8080
  • when this option is not specified:
    • HTTP proxy binds to: 80
    • HTTPS proxy binds to: 443
• --acl-ip restricts proxy server access to clients at IP addresses in whitelist
  • ex: "192.168.1.100,192.168.1.101,192.168.1.102"
• --api-keys restricts proxy server access to requests that include a key querystring parameter having a value in whitelist
  • ex: "1111,2222,3333,4444,5555"
• --req-insecure is a flag to override the following environment variable to disable certificate validation for secure https requests:
  • NODE_TLS_REJECT_UNAUTHORIZED= 0
    • equivalent to:
      • curl --insecure
      • wget --no-check-certificate
• --tls is a flag to start HTTPS proxy, rather than HTTP
  • used as shorthand to automatically configure the following options:
    • --tls-cert
    • --tls-key
    • --tls-pass
  • the values assigned to these options enable the use of a self-signed security certificate that is included in both the git repo and npm package, within the directory:
    • ./corsproxy/servers/cert
• --tls-cert is the filepath to a security certificate to use for HTTPS
• --tls-key is the filepath to the private key for the --tls-cert security certificate
• --tls-pass is the filepath to a text file containing the security passphrase for the --tls-key private key
  • optional, not required when the --tls-key private key was created without a security passphrase

Examples:

1. print help corsproxy --help

2. print version corsproxy --version

3. start HTTP proxy at default port corsproxy

4. start HTTP proxy at specific port corsproxy --port "8080"

5. start HTTPS proxy at default port corsproxy --tls

6. start HTTPS proxy at specific port corsproxy --tls --port "8081"

Installation and Usage: Working with a Local git Repo

How to: Install:

git clone "https://github.com/warren-bank/node-CORS-Proxy.git"
cd "node-CORS-Proxy"
npm install

How to: Run the server(s):

# ----------------------------------------------------------------------
# If using a port number >= 1024 on Linux, or
# If using Windows:
# ----------------------------------------------------------------------
npm start [-- <options>]

# ----------------------------------------------------------------------
# https://www.w3.org/Daemon/User/Installation/PrivilegedPorts.html
#
# Linux considers port numbers < 1024 to be privileged.
# Use "sudo":
# ----------------------------------------------------------------------
npm run sudo [-- <options>]

Options:

• identical to the command-line binary

Examples:

1. print help npm start -- --help

2. start HTTP proxy at specific port npm start -- --port "8080"

3. start HTTPS proxy at specific port npm start -- --port "8081" --tls

4. start HTTPS proxy at privileged port npm run sudo -- --port "443" --tls

Client Usage

Web Browser Configuration:

• for HTTP proxy:
  • by default, secure webpages cannot make requests to a non-secure server (ie: the HTTP proxy)
  • the following are instructions for Chromium browsers to allow all pages to access the HTTP proxy (ex: http://localhost:8080)
    1. Insecure origins treated as secure
       • open: chrome://flags/#unsafely-treat-insecure-origin-as-secure
       • enter: http://localhost:8080
       • set: Enabled
    2. [Chromium 100+] Block insecure private network requests
       • open: chrome://flags/#block-insecure-private-network-requests
       • set: Disabled
    3. restart Chrome
• for HTTPS proxy:
  • by default, the self-signed certificate used by the --tls option is untrusted
  • on Chromium browsers:
    • Chrome will add custom root certificates from the certificates used by your computer's operating system.
    • to open the root certificate management tool for your specific OS:
      • open: Settings > Privacy and security > Security > Advanced
      • click: Manage device certificates
  • on Windows OS:
    • open the root certificate management tool
      • press: Win + R
      • enter: certmgr.msc
    • import the private certificate authority used to self-sign the server certificate
      • right-click on: Trusted Root Certificate Authorities > Certificates
      • click: All Tasks > Import..
      • click: Next
      • browse:
        • set file filter: X.509 Certificate (*.cer,*.crt)
        • select file: ./corsproxy/servers/cert/ca.crt
        • click: Open
      • click: Next
      • click: Next
      • click: Finish
      • click: Yes
    • confirmation:
      • click on: Trusted Root Certificate Authorities > Certificates
      • find:
        • Issued To: CORS-proxy
        • Issued By: CORS-proxy
    • test:
      • open in Chromium: https://localhost:8081

Example for HTTP proxy:

1. start local corsproxy server:

     # npm start -- --port "8080" --api-keys "my-password" --req-insecure
     corsproxy --port "8080" --api-keys "my-password" --req-insecure

2. run in web browser JS console on any page:

     const api_url     = 'http://localhost:8080/'
     const api_key     = 'my-password'
     const req_url     = 'https://httpbin.org/anything'
     const req_headers = [{name: 'x-foo', value: 'req-foo'},{name: 'x-bar', value: 'req-bar'}]
     const res_headers = [{name: 'x-foo', value: 'res-foo'},{name: 'x-bar', value: 'res-bar'}]
   
     const qs_params = [`url=${encodeURIComponent(req_url)}`]
     if (api_key)
       qs_params.push(`key=${encodeURIComponent(api_key)}`)
     for(const {name: header_name, value: header_value} of req_headers) {
       qs_params.push(`reqHeaders=${encodeURIComponent(`${header_name}:${header_value || ''}`)}`)
     }
     for(const {name: header_name, value: header_value} of res_headers) {
       qs_params.push(`resHeaders=${encodeURIComponent(`${header_name}:${header_value || ''}`)}`)
     }
   
     let corsproxy_url = api_url || 'https://corsproxy.io/'
     corsproxy_url += '?' + qs_params.join('&')
   
     console.log(corsproxy_url)
     // http://localhost:8080/?url=https%3A%2F%2Fhttpbin.org%2Fanything&key=my-password&reqHeaders=x-foo%3Areq-foo&reqHeaders=x-bar%3Areq-bar&resHeaders=x-foo%3Ares-foo&resHeaders=x-bar%3Ares-bar
   
     fetch(corsproxy_url, {method: 'GET'})
       .then(res => res.json()).then(console.log)
   
     fetch(corsproxy_url, {method: 'POST', body: '{"hello": "world"}', headers: {'content-type': 'application/json'}})
       .then(res => res.json()).then(console.log)

Example for HTTPS proxy:

1. start local corsproxy server:

     # npm start -- --port "8081" --tls --api-keys "my-password" --req-insecure
     corsproxy --port "8081" --tls --api-keys "my-password" --req-insecure

2. run in web browser JS console on any page:

     const api_url     = 'https://localhost:8081/'
     const api_key     = 'my-password'
     const req_url     = 'https://httpbin.org/anything'
     const req_headers = [{name: 'x-foo', value: 'req-foo'},{name: 'x-bar', value: 'req-bar'}]
     const res_headers = [{name: 'x-foo', value: 'res-foo'},{name: 'x-bar', value: 'res-bar'}]
   
     const qs_params = [`url=${encodeURIComponent(req_url)}`]
     if (api_key)
       qs_params.push(`key=${encodeURIComponent(api_key)}`)
     for(const {name: header_name, value: header_value} of req_headers) {
       qs_params.push(`reqHeaders=${encodeURIComponent(`${header_name}:${header_value || ''}`)}`)
     }
     for(const {name: header_name, value: header_value} of res_headers) {
       qs_params.push(`resHeaders=${encodeURIComponent(`${header_name}:${header_value || ''}`)}`)
     }
   
     let corsproxy_url = api_url || 'https://corsproxy.io/'
     corsproxy_url += '?' + qs_params.join('&')
   
     console.log(corsproxy_url)
     // https://localhost:8081/?url=https%3A%2F%2Fhttpbin.org%2Fanything&key=my-password&reqHeaders=x-foo%3Areq-foo&reqHeaders=x-bar%3Areq-bar&resHeaders=x-foo%3Ares-foo&resHeaders=x-bar%3Ares-bar
   
     fetch(corsproxy_url, {method: 'GET'})
       .then(res => res.json()).then(console.log)
   
     fetch(corsproxy_url, {method: 'POST', body: '{"hello": "world"}', headers: {'content-type': 'application/json'}})
       .then(res => res.json()).then(console.log)

Legal:

• copyright: Warren Bank
• license: GPL-2.0