Registry / auth-security / strict-transport-security

strict-transport-security

JSON →
library0.3.0jsnpmunverified

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.

auth-securityweb-framework
npm install strict-transport-security
github ↗package ↗
INSTALL
IMPORT
SIG · STRICT-TRANSPORT-S
S
strict-transport-security
auth-securityjavascriptv0.3.0
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.

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
✓ app.use(sts.getSTS({'max-age':{'days': 30}}));
✗ app.use(require('strict-transport-security'));
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
✓ sts.getSTS({'max-age':{'days': 30}, 'includeSubDomains': true, 'preload': true});
✗ sts.getSTS('max-age=...');
The `getSTS` function expects a plain JavaScript object as its argument, containing properties like `max-age`, `includeSubDomains`, and `preload`.

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!'); });
Debug
Known issues
gotchaStrict-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.
affects: >=0.1.0
gotchaThe `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.
affects: >=0.3.0
gotchaUsing `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.
affects: >=0.1.0
Errors
Common errors & fixes
TypeError: app.use is not a function
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()`.
TypeError: sts.getSTS is not a function
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.
Cannot read properties of undefined (reading 'days') or similar configuration error
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}}`.
Upgrade
Version history
0.3.0latest on npm
Audit
Dependencies
expressoptionalCommonly used with this middleware, as it's designed for Express/Connect-style applications, though not a direct runtime dependency of the package itself.
connectoptionalThis package produces middleware compatible with the Connect interface, which Express is built upon. Many Node.js web frameworks support Connect-style middleware.
Agent activity
11 hits · last 30 days
node
10
OpenAI (training)
1
Resources
githubhttps://github.com/samuelerdtman/strict-transport-security ↗
packagehttps://www.npmjs.com/package/strict-transport-security ↗
strict-transport-security — npm install strict-transport-security · libregistry