ssl-proxy

# ssl-proxy

Terminate HTTPS locally for dev servers with auto-generated mkcert certificates. Zero browser security warnings.

## When to use

- Testing Stripe, PayPal, or any payment SDK that requires HTTPS
- Building Progressive Web Apps or service workers (HTTPS required)
- Testing secure cookies (`Secure` flag requires HTTPS)
- Reproducing mixed-content policy issues
- Any time you get "Not Secure" in the browser address bar on localhost
- OAuth flows that require a registered HTTPS redirect URI

## Prerequisites

1. mkcert installed: `brew install mkcert` (macOS), `choco install mkcert` (Windows), or download from https://github.com/FiloSottile/mkcert/releases
2. ssl-proxy installed globally
3. CA installed once: `ssl-proxy trust install`

## Installation

ssl-proxy is a global CLI tool. Do NOT add it as a project dependency.

```bash
npm install -g @your-org/ssl-proxy
```

## Quick Start

```bash
# One-time: install CA into system trust store
ssl-proxy trust install

# Start HTTPS proxy for your dev server on port 3000
ssl-proxy start --from 3000
# -> https://localhost:3443 -> http://localhost:3000
```

## Usage Patterns

### Basic proxy

```bash
ssl-proxy start --from 3000
# Starts: https://localhost:3443 -> http://localhost:3000
```

### Custom HTTPS port

```bash
ssl-proxy start --from 3000 --to 8443
# Starts: https://localhost:8443 -> http://localhost:3000
```

### Custom domain (requires /etc/hosts entry)

```bash
ssl-proxy cert generate myapp.test
ssl-proxy start --from 3000 --domain myapp.test
# Starts: https://myapp.test:3443 -> http://localhost:3000
# Add to /etc/hosts: 127.0.0.1  myapp.test
```

### Multiple proxies from project config

```bash
# Create .ssl-proxy.json in project root
ssl-proxy config init

# Edit .ssl-proxy.json, then start all proxies
ssl-proxy start
```

### List running proxies

```bash
ssl-proxy list
```

### Stop a proxy

```bash
ssl-proxy stop react-app   # by label
ssl-proxy stop a3b4c5d6   # by ID prefix
```

## Config File (.ssl-proxy.json)

Place in project root to define multiple proxies:

```json
{
  "proxies": [
    { "httpsPort": 3443, "httpPort": 3000, "label": "react-app" },
    { "httpsPort": 4443, "httpPort": 4000, "label": "api-server" }
  ]
}
```

Run `ssl-proxy start` with no arguments to start all defined proxies.

## CLI Reference

| Command | Description |
|---|---|
| `ssl-proxy start --from <port>` | Start HTTPS proxy |
| `ssl-proxy start --from <port> --to <port>` | Use specific HTTPS port |
| `ssl-proxy start --from <port> --domain <host>` | Use custom domain |
| `ssl-proxy start --from <port> --label <label>` | Add a label |
| `ssl-proxy stop <id-or-label>` | Stop a proxy |
| `ssl-proxy list` | List running proxies |
| `ssl-proxy status` | Daemon and proxy summary |
| `ssl-proxy cert list` | List all certificates |
| `ssl-proxy cert generate <domain>` | Generate cert for domain |
| `ssl-proxy cert revoke <id>` | Delete a certificate |
| `ssl-proxy trust install` | Install CA into system trust store |
| `ssl-proxy trust status` | Check CA trust status |
| `ssl-proxy config show` | Show current configuration |
| `ssl-proxy config init` | Create .ssl-proxy.json |

## Environment Variables

| Variable | Description | Default |
|---|---|---|
| `LSPROXY_DATA_DIR` | Data directory (SQLite, certs, socket) | `~/.local-ssl-proxy` |
| `LSPROXY_API_PORT` | Web dashboard port | `9443` |
| `LSPROXY_LOG_LEVEL` | Log level: debug, info, warn, error | `info` |
| `LSPROXY_LOG_RETENTION` | Request log retention days | `7` |
| `LSPROXY_MKCERT_PATH` | Override path to mkcert binary | (from PATH) |
| `LSPROXY_DEV` | Extra debug output (0 or 1) | `0` |

## Behavior

- **Auto-start daemon:** The daemon starts automatically when you run `ssl-proxy start`. No manual daemon management needed.
- **Certificate reuse:** If a valid cert for the domain already exists, it is reused. No unnecessary cert generation.
- **Request logging:** All proxied requests are logged to SQLite and visible in the dashboard at http://127.0.0.1:9443.
- **Header redaction:** Authorization and Cookie headers are stripped from stored request logs.

## Troubleshooting

### "mkcert not found in PATH"

Install mkcert: `brew install mkcert` (macOS) or see https://github.com/FiloSottile/mkcert/releases

### Browser still shows security warning after trust install

Restart your browser. Chrome and Firefox require a restart to pick up new CA certificates.

### "port N is already in use"

Another process (or another ssl-proxy) is using that port. Use `--to <different-port>` or stop the conflicting process.

### HTTPS proxy starts but returns 502

Your dev server (the `--from` port) is not running. Start your dev server first, then the proxy will work automatically.

### Custom domain not resolving

Add an entry to `/etc/hosts`: `127.0.0.1  myapp.test`. The cert is valid but the OS needs to know where to route the hostname.