Registry / http-networking / local-ssl-proxy

local-ssl-proxy

library2.0.5jsnpmunverified

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.

http-networking auth-security devops

npm install local-ssl-proxy

github ↗package ↗

INSTALL

IMPORT

SIG · LOCAL-SSL-PROXY

local-ssl-proxy

http-networkingjavascriptv2.0.5

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

CLI usage

✓ npx local-ssl-proxy --source 9001 --target 9000

✗ local-ssl-proxy

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.

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

local-ssl-proxy --version

Debug

Known issues

breakingOlder 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.

affects: <2.0.0

gotchaThe 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.

affects: >=1.0.0

breakingThis 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.

affects: >=1.0.0

gotchaWhen 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.

affects: >=1.0.0

Errors

Common errors & fixes

ERR_CERT_AUTHORITY_INVALID / NET::ERR_CERT_AUTHORITY_INVALID

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>

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

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.

Upgrade

Version history

2.0.5latest on npm

Audit

Dependencies

mkcertoptionalRecommended for generating locally trusted SSL certificates to avoid browser warnings during development.

Agent activity

11 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/cameronhunter/local-ssl-proxy ↗

packagehttps://www.npmjs.com/package/local-ssl-proxy ↗