hsts

What is hsts?

The 'hsts' npm package is used to set the HTTP Strict Transport Security (HSTS) header in web applications. This header is used to enforce secure (HTTP over SSL/TLS) connections to the server.

What are hsts's main functionalities?

Basic HSTS Header Setup

This code sets up a basic Express server and uses the 'hsts' middleware to set the HSTS header with a max age of 1 year (31536000 seconds).

const hsts = require('hsts');
const express = require('express');
const app = express();

app.use(hsts({ maxAge: 31536000 })); // 1 year in seconds

app.get('/', (req, res) => {
  res.send('Hello, world!');
});

app.listen(3000, () => {
  console.log('Server is running on port 3000');
});

HSTS with Subdomains

This code sets the HSTS header to include subdomains by setting the 'includeSubDomains' option to true.

const hsts = require('hsts');
const express = require('express');
const app = express();

app.use(hsts({ maxAge: 31536000, includeSubDomains: true }));

app.get('/', (req, res) => {
  res.send('Hello, world!');
});

app.listen(3000, () => {
  console.log('Server is running on port 3000');
});

HSTS with Preload

This code sets the HSTS header with the 'preload' option, which allows the domain to be included in browsers' HSTS preload lists.

const hsts = require('hsts');
const express = require('express');
const app = express();

app.use(hsts({ maxAge: 31536000, preload: true }));

app.get('/', (req, res) => {
  res.send('Hello, world!');
});

app.listen(3000, () => {
  console.log('Server is running on port 3000');
});

Other packages similar to hsts

helmet

Helmet is a comprehensive security middleware for Express applications. It includes various security headers, including HSTS, making it a more feature-rich alternative to the 'hsts' package. Helmet can be used to set multiple security headers with a single middleware.

README

HTTP Strict Transport Security middlware

Trying to prevent: Users viewing your site on HTTP instead of HTTPS. HTTP is pretty insecure.

How this mitigates this: This middleware adds the Strict-Transport-Security header to the response. This tells browsers, "hey, only use HTTPS for the next period of time". (See the spec for more.)

This will set the Strict Transport Security header, telling browsers to visit by HTTPS for the next ninety days:

var hsts = require('hsts');

var ninetyDaysInMilliseconds = 7776000000;
app.use(hsts({ maxAge: ninetyDaysInMilliseconds }));

You can also include subdomains. If this is set on example.com, supported browsers will also use HTTPS on my-subdomain.example.com. Here's how you do that:

app.use(hsts({
  maxAge: 123000,
  includeSubDomains: true
}));

Chrome lets you submit your site for baked-into-Chrome HSTS by adding preload to the header. You can add that with the following code, and then submit your site to the Chrome team at hstspreload.appspot.com.

app.use(hsts({
  maxAge: 10886400000,     // Must be at least 18 weeks to be approved by Google
  includeSubDomains: true, // Must be enabled to be approved by Google
  preload: true
}));

This'll be set if req.secure is true, a boolean auto-populated by Express. If you're not using Express, that value won't necessarily be set, so you have two options:

// Set the header based on conditions
app.use(hsts({
  maxAge: 1234000,
  setIf: function(req, res) {
    return Math.random() < 0.5;
  }
}));

// ALWAYS set the header
app.use(hsts({
  maxAge: 1234000,
  force: true
}));

Note that the max age is in milliseconds, even though the spec uses seconds. This will round to the nearest full second.

Limitations: This only works if your site actually has HTTPS. It won't tell users on HTTP to switch to HTTPS, it will just tell HTTPS users to stick around. You can enforce this with the express-enforces-ssl module. It's somewhat well-supported by browsers.