fbi-proxy 1.3.0

A fast and flexible proxy server for intercepting and modifying HTTP/HTTPS requests
fbi-proxy-1.3.0 is not a library.

fbi-proxy

FBI Proxy is a super easy way to turn your local network over HTTPS with intelligent domain routing.

Quick Start

# Install dependencies
bun install

# Build and start the proxy system
bun run start

# Development mode with auto-reload
bun run dev

Build Scripts

Available Commands:

# Build TypeScript CLI
bun run build:ts

# Build Rust proxy binary
bun run build:rs

# Full build (both TypeScript and Rust)
bun run build

# Development with hot reload
bun run dev

# Production start
bun run start

Architecture

The FBI Proxy consists of three main components:

  • TypeScript CLI (ts/cli.ts): Orchestrates the entire system, manages Caddy and Rust proxy processes
  • Rust Proxy Server (proxy.rs): High-performance HTTP/WebSocket proxy using Hyper framework
  • Caddy Server: Handles TLS termination, SSL certificates, and domain routing

How It Works

  1. CLI downloads/manages Caddy binary and builds the Rust proxy
  2. Caddy receives incoming HTTPS requests and forwards them to the Rust proxy
  3. Rust Proxy intelligently routes requests based on hostname patterns

Development Workflow

First Time Setup:

# 1. Install dependencies (requires Bun)
bun install

# 2. Start development (automatically builds and runs)
bun run dev

Daily Development:

# Development with hot reload for both Caddy and Rust
bun run dev

# Or run individual components:
bun run dev:caddy    # Start Caddy with file watching
bun run dev:rs       # Start Rust proxy with bacon (auto-rebuild)

Production Deployment:

bun run build       # Build optimized binaries
bun run start       # Start production services

Prerequisites

  • Bun: JavaScript runtime and package manager (install from https://bun.sh/)
  • Rust: For building the proxy binary (install from https://rustup.rs/)
  • Caddy: Automatically downloaded by the CLI if not found

Routing Features

The FBI Proxy supports intelligent hostname-based routing with the following patterns:

1. Port Forwarding

  • https://3000.fbi.com → http://localhost:3000
  • https://8080.fbi.com → http://localhost:8080

2. Host--Port Forwarding

  • https://localhost--3000.fbi.com → http://localhost:3000
  • https://myserver--8080.fbi.com → http://myserver:8080

3. Subdomain Hoisting

  • https://api.myserver.fbi.com → http://myserver:80 (with Host: api)
  • https://admin.localhost.fbi.com → http://localhost:80 (with Host: admin)

4. Direct Host Forwarding

  • https://myserver.fbi.com → http://myserver:80
  • https://localhost.fbi.com → http://localhost:80

WebSocket Support

All routing patterns support WebSocket connections with automatic upgrade handling.

Configuration

Environment Variables

FBIHOST="fbi.com"           # Default domain (configurable via --fbihost)
FBIPROXY_PORT="24306"       # Internal proxy port (auto-assigned)

CLI Options

bun run ts/cli.ts --help

Options:
  --help          Show help message
  --fbihost       Set the FBI host (default: fbi.com)

Service Configuration Examples

Create custom service mappings by modifying the routing logic or using the built-in patterns:

# Direct port access
https://3000.fbi.com        # → localhost:3000
https://5173.fbi.com        # → localhost:5173 (Vite dev server)
https://8000.fbi.com        # → localhost:8000 (VS Code server)

# Named services with custom ports
https://api--3001.fbi.com   # → api:3001
https://db--5432.fbi.com    # → db:5432

# Subdomain routing
# Subdomain routing
https://admin.app.fbi.com   # → app:80 with Host: admin
https://v2.api.fbi.com      # → api:80 with Host: v2

Technical Details

Rust Proxy Implementation (proxy.rs)

The Rust proxy server implements the following routing logic:

  1. Number Host Detection: Pure numeric hosts (e.g., 3000) route to localhost:3000
  2. Double-Dash Parsing: host--port format routes to host:port
  3. Subdomain Hoisting: Multi-level domains route to the root domain with subdomain as Host header
  4. Default Port 80: Simple hostnames default to port 80

TypeScript CLI (ts/cli.ts)

The CLI manages:

  • Binary discovery and building (Rust proxy, Caddy download)
  • Process orchestration with proper signal handling
  • Port management and environment variable passing
  • Hot reloading during development

Caddy Configuration (Caddyfile)

  • Automatic HTTPS with on-demand TLS certificates
  • Regex-based host header matching
  • Reverse proxy configuration with header manipulation
  • Support for wildcard subdomain routing

License

MIT License - see LICENSE file for details