smallprox/README.md

# smallprox

**smallprox** is a lightweight, zero-dependency reverse proxy written in Go. It accepts incoming client connections over **TLS 1.2** (or configurable TLS versions) and forwards requests to backends running modern TLS protocols (such as TLS 1.3) or any SSL/TLS version.

## Key Features

- **TLS Protocol Bridging**: Solves the incompatibility where legacy clients (e.g. PowerShell scripts configured for TLS 1.2) need to access backends requiring TLS 1.3.
- **Zero Configuration HTTPS**: Generates an in-memory self-signed certificate on startup with localhost and IP Subject Alternative Names (SANs) if no cert/key files are provided.
- **Full Backend Trust**: Bypasses backend certificate checks (`InsecureSkipVerify: true`) to work with self-signed, untrusted, or internal certificates.
- **Virtual Host & SNI Support**: Automatically updates the `Host` header to match the destination backend (can be disabled with `-preserve-host`).
- **Zero External Dependencies**: Built entirely with Go standard library (`net/http`, `crypto/tls`, `crypto/x509`, `net/http/httputil`).

---

## Installation & Building

```powershell
# Clone and build
cd smallprox
go build -o smallprox.exe .
```

---

## Usage

```powershell
smallprox -backend <url> [options]
```

If no backend is provided, usage instructions are automatically printed.

### Command-line Options

| Flag | Short | Default | Description |
|------|-------|---------|-------------|
| `-backend` | `-b` | *(Required)* | Target backend URL (e.g. `https://tls13.example.com`) |
| `-listen` | `-l` | `:8443` | Address and port to bind |
| `-tls-min` | | `1.2` | Minimum incoming TLS version (`1.0`, `1.1`, `1.2`, `1.3`) |
| `-tls-max` | | `1.2` | Maximum incoming TLS version (`1.0`, `1.1`, `1.2`, `1.3`) |
| `-cert` | | | Path to custom TLS certificate PEM file (optional) |
| `-key` | | | Path to custom TLS private key PEM file (optional) |
| `-http` | | `false` | Listen in plain HTTP mode instead of HTTPS |
| `-preserve-host` | | `false` | Preserve incoming Host header instead of target host |
| `-version` | `-v` | | Print version and exit |
| `-help` | `-h` | | Show help message |

---

## Examples

### 1. Basic TLS 1.2 Proxy to TLS 1.3 Backend
```powershell
.\smallprox.exe -backend https://api.example.com
```
*Listens on `https://127.0.0.1:8443` with TLS 1.2 and proxies to `https://api.example.com`.*

### 2. Custom Port and TLS Range
```powershell
.\smallprox.exe -listen :9443 -backend https://api.example.com -tls-min 1.2 -tls-max 1.3
```

### 3. Using Custom Certificates
```powershell
.\smallprox.exe -backend https://api.example.com -cert server.crt -key server.key
```

### 4. Plain HTTP Ingress to HTTPS Backend
```powershell
.\smallprox.exe -http -listen :8080 -backend https://api.example.com
```

---

## PowerShell Client Example

To communicate through `smallprox` from a PowerShell session requiring TLS 1.2 and trusting self-signed certificates:

```powershell
# Enforce TLS 1.2 in PowerShell
[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12

# Trust local self-signed certificate
[System.Net.ServicePointManager]::ServerCertificateValidationCallback = {$true}

# Make request through proxy
$response = Invoke-RestMethod -Uri "https://localhost:8443/api/v1/resource" -Method Get
Write-Output $response
```

---

## Running Tests

```powershell
go test -v ./...
```