Skip to content

Latest commit

 

History

History
227 lines (171 loc) · 5.02 KB

README.md

File metadata and controls

227 lines (171 loc) · 5.02 KB

DFanso Tunnel Server

A secure tunneling solution that allows you to expose your local servers to the internet through custom subdomains. Built with Node.js, WebSocket, and SSL support.

Features

  • 🔒 Secure SSL tunneling with Let's Encrypt
  • 🌐 Custom subdomain support (*.dfanso.dev)
  • 🚀 HTTP/2 support
  • 🔄 WebSocket-based tunneling
  • 📦 Official npm client package: @dfanso/tunnel-client
  • 🛡️ Production-ready with error handling

Architecture

Internet (HTTPS) -> Tunnel Server (dfanso.dev) -> WebSocket -> Local Server

Server Setup

Prerequisites

  • Node.js 16+
  • Let's Encrypt SSL certificate
  • Domain with wildcard DNS (*.dfanso.dev)
  • Add a CNAME record for your domain to point to the tunnel server

Installation

git clone https://github.com/dfanso/tunnel-server.git
cd tunnel-server
npm install

Configuration

Create a .env file:

NODE_ENV=production
DOMAIN=dfanso.dev
HTTP_PORT=80
HTTPS_PORT=443
WS_PORT=8080
SSL_DIR=/etc/letsencrypt/live/dfanso.dev

SSL Certificate Setup

  1. Install certbot:
sudo apt-get install certbot
  1. Generate wildcard certificate:
sudo certbot certonly --manual --preferred-challenges dns -d *.dfanso.dev -d dfanso.dev
# First install the Cloudflare certbot plugin
sudo apt install python3-certbot-dns-cloudflare  # for Ubuntu/Debian

# Create a Cloudflare API token configuration file
sudo mkdir -p /etc/cloudflare
sudo nano /etc/cloudflare/cloudflare.ini

# Add these lines to cloudflare.ini:
# dns_cloudflare_email = [email protected]
# dns_cloudflare_api_key = your-global-api-key

# Secure the file
sudo chmod 600 /etc/cloudflare/cloudflare.ini

# Then run certbot with the Cloudflare plugin
sudo certbot certonly --dns-cloudflare --dns-cloudflare-credentials /etc/cloudflare/cloudflare.ini -d *.dfanso.dev -d dfanso.dev
  1. Follow certbot instructions to add DNS TXT records

Running the Server

Development:

npm run dev

Production:

npm run build
npm start

Connecting to the Server

Using the Official npm Client

The recommended way to connect to this tunnel server is using our official npm package @dfanso/tunnel-client.

  1. Install the package:
npm install @dfanso/tunnel-client
  1. Basic usage:
const TunnelClient = require('@dfanso/tunnel-client');

const tunnel = new TunnelClient({
    subdomain: 'myapp',     // Will be myapp.dfanso.dev
    targetPort: 3000        // Your local server port
});

tunnel.connect()
    .then(({ url }) => {
        console.log(`Server is accessible at: ${url}`);
    })
    .catch(console.error);
  1. With Express.js:
const TunnelClient = require('@dfanso/tunnel-client');
const express = require('express');

const app = express();
app.use(express.json());

app.get('/', (req, res) => {
    res.send('Hello from tunneled server!');
});

const server = app.listen(3000, () => {
    const tunnel = new TunnelClient({
        subdomain: 'myapp',
        targetPort: 3000
    });

    tunnel.connect()
        .then(({ url }) => {
            console.log(`Server is accessible at: ${url}`);
        })
        .catch(console.error);
});

Client Configuration Options

{
    tunnelServer: 'wss://dfanso.dev:8080', // Tunnel server URL
    subdomain: 'myapp',                     // Your subdomain
    targetPort: 3000,                       // Your local server port
    localPort: 0,                           // Random port (optional)
    rejectUnauthorized: true                // Verify SSL (recommended)
}

Client Events

The client emits the following events:

  • connect: When tunnel connection is established
  • disconnect: When tunnel connection is lost
  • error: When an error occurs
  • request: When a request comes through the tunnel

Security

  • All traffic is encrypted with SSL
  • Automatic HTTP to HTTPS redirection
  • WebSocket connections are secured
  • Client verification through SSL

Project Structure

├── src/
│   ├── index.ts              # Server entry point
│   ├── server/
│   │   ├── HttpServer.ts     # HTTP/HTTPS server
│   │   └── WebSocketServer.ts# WebSocket handling
│   └── services/
│       └── TunnelService.ts  # Tunnel management
├── lib/
│   └── tunnel-client.js      # Client library
└── examples/
    └── example.js            # Usage examples

Testing

Start the test server:

node test-server.js

Connect with test client:

node test-client.js

Test endpoints:

curl https://test.dfanso.dev/
curl -X POST https://test.dfanso.dev/api/data -d '{"hello":"world"}'

Production Deployment

  1. Set up SSL certificates
  2. Configure environment variables
  3. Start with process manager:
npm install -g pm2
pm2 start npm --name "tunnel-server" -- start

License

MIT

Author

DFanso (https://github.com/dfanso)