Strict-Transport-Security Middleware

0.3.0 verified Thu Apr 23 auth: no javascript maintenance

The `strict-transport-security` package provides Node.js middleware designed to add the Strict-Transport-Security (HSTS) header to HTTP responses. This header enforces secure (HTTPS) connections, preventing downgrade attacks and cookie hijacking in compliant browsers, as specified by RFC6797. It is built to integrate seamlessly with Express.js and Connect-compatible frameworks, allowing developers to define global or path-specific HSTS policies. The package is currently at version 0.3.0, with its latest notable update introducing support for the `preload` option. Its development cadence suggests a mature and stable, yet likely low-maintenance, library focused on a singular security concern. Its primary differentiator is its dedicated functionality for HSTS, offering a lightweight alternative to larger security middleware suites.

Common errors

error TypeError: app.use is not a function ↓

cause Attempting to use the middleware without having an initialized Express or Connect application instance.

fix

Ensure you have an Express or Connect application instance (e.g., const app = express();) before calling app.use().

error TypeError: sts.getSTS is not a function ↓

cause The `sts` variable from `require('strict-transport-security')` is either undefined, or the module failed to load, or `getSTS` was called on an incorrect object.

fix

Verify that strict-transport-security is correctly installed (npm install strict-transport-security --save) and that the require() path is accurate. Ensure you are calling getSTS on the correct sts module object.

error Cannot read properties of undefined (reading 'days') or similar configuration error ↓

cause Incorrect format for the `max-age` option within the `getSTS` configuration object.

fix

The max-age option expects an object with a duration property (e.g., days, seconds), for example: {'max-age': {'days': 30}}.

Warnings

gotcha Strict-Transport-Security (HSTS) headers are aggressively cached by client browsers. Once a policy is set with a significant `max-age`, browsers will *only* attempt HTTPS connections to your domain for that duration. Misconfiguring HSTS, especially with `includeSubDomains` or `preload`, can make your site inaccessible if HTTPS setup is incorrect or later removed. ↓

fix Thoroughly test HSTS policies in development before deploying to production. Start with a short `max-age` for testing and gradually increase. Always ensure your server enforces HTTPS redirects *before* HSTS headers are applied.

gotcha The `preload` option, introduced in v0.3.0, indicates your intent to be included in browser HSTS preload lists. Submitting your domain to these lists (e.g., hstspreload.org) makes browsers *always* connect via HTTPS to your domain, even on the very first visit. This is an irreversible decision for most practical purposes and requires perfect, indefinite HTTPS availability for your entire domain and subdomains. ↓

fix Only enable `preload` and submit to HSTS preload lists if you are absolutely confident in your long-term HTTPS strategy and infrastructure. Any HTTPS outage or misconfiguration after preloading will render your site unusable for a significant portion of users.

gotcha Using `strict-transport-security` middleware without ensuring your application server globally redirects all HTTP traffic to HTTPS will still leave the very first connection vulnerable to downgrade attacks. The HSTS header is only sent *after* a successful HTTPS connection. ↓

fix Configure your web server (e.g., Nginx, Apache) or your application's entry point to perform a 301 (Permanent) redirect from HTTP to HTTPS for all incoming requests before this middleware is executed.

Install

npm install strict-transport-security

yarn add strict-transport-security

pnpm add strict-transport-security

Imports

getSTS factory (CommonJS)
```
const sts = require('strict-transport-security');
```
The package primarily targets CommonJS environments. The `getSTS` factory function is accessed as a property of the module object returned by `require`. This is the intended primary usage pattern for this package.
HSTS Middleware Application
wrong
```
app.use(require('strict-transport-security'));
```
correct
```
app.use(sts.getSTS({'max-age':{'days': 30}}));
```
Remember to call the `getSTS()` function with your desired configuration to obtain the actual middleware function. Do not attempt to use the imported module directly as middleware.
Configuration Object
wrong
```
sts.getSTS('max-age=...');
```
correct
```
sts.getSTS({'max-age':{'days': 30}, 'includeSubDomains': true, 'preload': true});
```
The `getSTS` function expects a plain JavaScript object as its argument, containing properties like `max-age`, `includeSubDomains`, and `preload`.

Quickstart

Demonstrates how to initialize and apply Strict-Transport-Security middleware globally across all requests and how to define and apply a path-specific policy that overrides the global one within an Express.js application.

const sts = require('strict-transport-security');
const express = require('express');
const app = express();

const globalSTS = sts.getSTS({'max-age':{'days': 30}});
const localSTS = sts.getSTS({'max-age':{'days': 10}, 'includeSubDomains': true});

// This will apply this policy to all requests
app.use(globalSTS);

app.get('/', (req, res) => {
  res.send('Using global strict transport security policy!');
});

// This will apply the local policy just to this path, overriding the global policy
app.get('/local', localSTS, (req, res) => {
  res.send('Using path local strict transport security policy!');
});

app.listen(3000, () => {
  console.log('Example app listening on port 3000!');
});