Registry / web-framework / redirect-https

redirect-https

library1.3.1jsnpmunverified

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.

web-framework auth-security

npm install redirect-https

package ↗homepage ↗

INSTALL

IMPORT

SIG · REDIRECT-HTTPS

redirect-https

web-frameworkjavascriptv1.3.1

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.

redirectorFactory

✓ const redirector = require('redirect-https')({ /* options */ });

✗ import redirector from 'redirect-https';

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.

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: "", trustProxy: true // default is false }); server.on("request", redirector); server.listen(insecurePort, function () { console.log( "Listening on http://localhost.rootprojects.org:" + server.address().port ); });

Debug

Known issues

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

affects: >=1.0.0

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

affects: >=1.0.0

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

affects: >=1.0.0

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

affects: >=1.0.0

Errors

Common errors & fixes

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

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 });`.

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

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 });`.

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

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.

Upgrade

Version history

1.3.1latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

20 hits · last 30 days

node

Amazon

OpenAI (training)

Resources

packagehttps://www.npmjs.com/package/redirect-https ↗

homepagehttps://git.coolaj86.com/coolaj86/redirect-https.js#readme ↗