HTTP to HTTPS Redirect Middleware

1.3.1 verified Thu Apr 23 auth: no javascript maintenance

redirect-https is a Node.js middleware designed for securing web applications by forcing HTTP traffic to HTTPS. It primarily functions by issuing a 301 (Moved Permanently) redirect for browsers while opting for an HTML meta refresh redirect for non-browser clients like APIs, bots, and `curl` requests. This deliberate choice aims to make developers aware of insecure HTTP usage, preventing silent failures often associated with direct 301s for programmatic access. The package is currently at version 1.3.1 and is a mature, stable utility with an infrequent release cadence, focusing on its core secure-by-default philosophy rather than extensive configurability. It is compatible with Express.js and standard Node.js `http` servers, offering options for custom body messages, proxy trust configuration, and specific path matching for advanced scenarios. Its key differentiator is the "secure-by-default" meta redirect strategy to surface security issues to developers.

Common errors

error Error: read ECONNRESET / curl: (18) transfer closed with 0 bytes received ↓

cause Attempts to fetch resources from an HTTP endpoint using `curl` or similar command-line tools fail unexpectedly, especially when the default meta redirect behavior is active.

fix

This is often the intended behavior of redirect-https to highlight insecure usage. To allow curl to receive a 301 redirect, configure the apis option: redirector = require('redirect-https')({ apis: 301 });.

error My application isn't redirecting to HTTPS, or it's stuck in a redirect loop when deployed behind a load balancer. ↓

cause The server isn't correctly identifying that the request originated via HTTPS, likely due to a reverse proxy (like Nginx, AWS ELB) terminating TLS and forwarding as HTTP.

fix

Ensure the trustProxy option is set to true when initializing redirect-https to correctly interpret X-Forwarded-Proto headers from the proxy: redirector = require('redirect-https')({ trustProxy: true });.

error The `{{ URL }}` or `{{ HTML_URL }}` placeholders in the custom body are not correctly escaping special characters or are being exploited. ↓

cause While `redirect-https` performs HTML escaping, using `{{ UNSAFE_URL }}` directly in the `body` option can expose the application to cross-site scripting (XSS) vulnerabilities if the original URL contains malicious input.

fix

Always prefer {{ URL }} or {{ HTML_URL }} which are safely escaped. Avoid using {{ UNSAFE_URL }} in user-facing content unless you have performed your own sanitization.

Warnings

gotcha By default, `redirect-https` uses HTML meta redirects for non-browser user agents (like `curl`, APIs, bots). This is an intentional security feature to make developers aware of insecure HTTP calls, but it will break command-line tools and programmatic API requests that expect a direct 3xx HTTP redirect. ↓

fix If direct 301 redirects are desired for APIs or bots, configure the `apis` option: `require('redirect-https')({ apis: 301 })`. Consider the security implications before doing so.

gotcha When running behind a reverse proxy (e.g., Nginx, AWS ELB, Heroku) that handles TLS termination, `redirect-https` might incorrectly redirect if it doesn't know the original protocol was HTTPS. This is because the connection to Node.js itself is HTTP. ↓

fix Enable the `trustProxy` option: `require('redirect-https')({ trustProxy: true })`. This makes the middleware inspect `X-Forwarded-Proto` headers to determine the client's original protocol.

gotcha The `paths` option allows fine-grained control over redirects for specific paths, but the documentation advises against getting "too fancy." Over-complicating redirect logic can introduce bugs or reduce maintainability. ↓

fix Prefer the default behavior or general options. Only use `paths` for very specific, well-understood edge cases, such as handling `curl | bash` installers that require a 301 on `/`.

gotcha The package does not support custom redirect strategies based on specific HTTP methods (e.g., only redirect GET requests). All requests to an insecure endpoint will be redirected according to the configured rules. ↓

fix If method-specific redirection is required, implement a custom middleware or conditional logic before `redirect-https`.

Install

npm install redirect-https

yarn add redirect-https

pnpm add redirect-https

Imports

redirectorFactory
wrong
```
import redirector from 'redirect-https';
```
correct
```
const redirector = require('redirect-https')({ /* options */ });
```
This package is a CommonJS module. The `require` call returns a function that acts as middleware when invoked with options. Direct ESM `import` is not supported without transpilation or tools like `esm`.
createRedirectMiddleware
```
const createRedirectMiddleware = require('redirect-https');
const redirector = createRedirectMiddleware({ port: 443 });
```
The module exports a function that should be called to create the actual middleware. It is not intended to be used directly without configuration.
redirect-https middleware
```
app.use('/', require('redirect-https')({ trustProxy: true }));
```
The generated middleware function is typically passed directly to an HTTP server's request listener or an Express.js app's `use` method.

Quickstart

This example demonstrates how to set up `redirect-https` with a standard Node.js HTTP server, forcing redirects from an insecure port to a secure one, and configuring `trustProxy` for reverse proxy setups.

"use strict";

var http = require("http");
var server = http.createServer();
var securePort = process.argv[2] || 8443;
var insecurePort = process.argv[3] || 8080;

var redirector = require("redirect-https")({
    port: securePort,
    body: "<!-- Hello! Please use HTTPS instead: {{ URL }} -->",
    trustProxy: true // default is false
});

server.on("request", redirector);

server.listen(insecurePort, function () {
    console.log(
        "Listening on http://localhost.rootprojects.org:" +
            server.address().port
    );
});