Simple Local HTTPS Proxy

2.0.5 · active · verified Wed Apr 22

local-ssl-proxy is a lightweight utility designed to create an HTTPS proxy for local development. It leverages a self-signed SSL certificate, allowing developers to access local HTTP servers over HTTPS. This functionality is critical for testing applications that require a secure context, such as those using OAuth, secure cookies, geolocation APIs, or needing to avoid mixed-content warnings. The current stable version is 2.0.5, last updated in March 2023. While specific release cadence isn't formalized, updates typically address dependencies or minor enhancements. Its primary differentiators are its ease of use via the command line for quick setup, support for custom certificates (e.g., generated by `mkcert` for a trusted browser experience), and the ability to manage multiple proxy configurations through a single file, making it a flexible choice for diverse local development workflows. It is strictly intended for local development and should never be used in production environments.

Common errors

```
ERR_CERT_AUTHORITY_INVALID / NET::ERR_CERT_AUTHORITY_INVALID
```
cause The browser does not trust the self-signed certificate generated by `local-ssl-proxy` by default.

fix Accept the warning and proceed (for temporary testing) or, for a better development experience, use `mkcert` to generate locally trusted certificates and configure `local-ssl-proxy` to use them.
```
Error: listen EADDRINUSE: address already in use :::<port>
```
cause The specified `source` or `target` port is already being used by another process on your system.

fix Choose a different available port for the `source` or `target` (e.g., `--source 9443` or `--target 8000`). You can identify the process using the port with `lsof -i :<port>` on Unix-like systems or `netstat -ano | findstr :<port>` on Windows.
```
Proxy is not redirecting or connection refused on target port
```
cause The backend HTTP server is not running on the `target` port, or there's a firewall blocking the connection between the proxy and the target server.

fix Ensure your HTTP application is actively running and listening on the `target` port specified for `local-ssl-proxy`. Check your firewall settings to allow traffic on both the `source` and `target` ports.

Warnings

breaking Older versions of `local-ssl-proxy` might have different command-line arguments or configuration options. Ensure you are using the correct syntax for version 2.x, as breaking changes can occur between major releases (e.g., v1 to v2).
Fix: Refer to the `local-ssl-proxy` GitHub repository or npm page for specific version documentation. It is generally recommended to use the latest stable version and update your scripts accordingly.
gotcha The proxy uses self-signed certificates by default, which will trigger browser security warnings (e.g., 'Your connection is not private'). While safe for local development, this can be disruptive.
Fix: To avoid browser warnings, install `mkcert` (e.g., `brew install mkcert` on macOS, `choco install mkcert` on Windows), run `mkcert -install`, and then `mkcert localhost`. Configure `local-ssl-proxy` to use these generated `localhost.pem` and `localhost-key.pem` files with the `--cert` and `--key` flags.
breaking This tool is strictly for local development environments. Using `local-ssl-proxy` with its self-signed certificates or for untrusted domains in production or publicly accessible environments poses severe security risks, including vulnerability to Man-in-the-Middle attacks.
Fix: NEVER use `local-ssl-proxy` in production. For production HTTPS, always use professionally issued certificates from trusted Certificate Authorities (e.g., Let's Encrypt) and dedicated reverse proxies like Nginx or Caddy.
gotcha When using `local-ssl-proxy` to handle multiple proxy configurations via a JSON config file, ensure the file format precisely matches the expected structure. Incorrect keys or values can lead to unexpected behavior or proxy failure.
Fix: Always refer to the official documentation for the correct config file schema. An example structure includes objects where keys are proxy names, and values are objects with `source`, `target`, `key`, `cert`, and `hostname` properties.

Install

npm install local-ssl-proxy npm
yarn add local-ssl-proxy yarn
pnpm add local-ssl-proxy pnpm

Imports

CLI usage
wrong:
```
local-ssl-proxy
```
correct:
```
npx local-ssl-proxy --source 9001 --target 9000
```
The primary way to use this package is via its command-line interface. `npx` is recommended for on-demand use, or `npm install -g local-ssl-proxy` for global installation.
start
```
import { start } from 'local-ssl-proxy';
// or
const { start } = require('local-ssl-proxy');
```
While primarily a CLI tool, the package exports a `start` function for programmatic control. This is useful for integrating the proxy into build scripts or other Node.js applications.

Quickstart

This example demonstrates how to programmatically start `local-ssl-proxy` to proxy HTTPS traffic from port 9001 to an underlying HTTP server on port 3000. It also shows the equivalent CLI command. This setup is ideal for local development and requires pre-generated `mkcert` certificates for a trusted experience.

import { start } from 'local-ssl-proxy';
import http from 'http';

// Start a simple HTTP server on port 3000
const httpServer = http.createServer((req, res) => {
  res.writeHead(200, { 'Content-Type': 'text/plain' });
  res.end('Hello from HTTP server on port 3000!');
});
httpServer.listen(3000, () => {
  console.log('HTTP server running on http://localhost:3000');
});

// Start local-ssl-proxy to proxy HTTPS (9001) to HTTP (3000)
// You'll likely need to generate trusted certs with mkcert first:
// mkcert -install && mkcert localhost
start({
  source: 9001,
  target: 3000,
  key: 'localhost-key.pem', // Path to your generated key
  cert: 'localhost.pem'   // Path to your generated cert
})
  .then(() => {
    console.log('HTTPS proxy running on https://localhost:9001');
    console.log('Access your HTTP server via https://localhost:9001');
  })
  .catch(err => {
    console.error('Failed to start proxy:', err.message);
    process.exit(1);
  });

// CLI equivalent (run in terminal):
// npx local-ssl-proxy --source 9001 --target 3000 --key localhost-key.pem --cert localhost.pem

view raw JSON →