{"id":17962,"library":"strict-transport-security","title":"Strict-Transport-Security Middleware","description":"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.","status":"maintenance","version":"0.3.0","language":"javascript","source_language":"en","source_url":"ssh://git@github.com/samuelerdtman/strict-transport-security","tags":["javascript","express","connect","strict-transport-security","Strict Transport Security","security","SSL","TLS","HTTPS"],"install":[{"cmd":"npm install strict-transport-security","lang":"bash","label":"npm"},{"cmd":"yarn add strict-transport-security","lang":"bash","label":"yarn"},{"cmd":"pnpm add strict-transport-security","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Commonly used with this middleware, as it's designed for Express/Connect-style applications, though not a direct runtime dependency of the package itself.","package":"express","optional":true},{"reason":"This package produces middleware compatible with the Connect interface, which Express is built upon. Many Node.js web frameworks support Connect-style middleware.","package":"connect","optional":true}],"imports":[{"note":"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.","symbol":"getSTS factory (CommonJS)","correct":"const sts = require('strict-transport-security');"},{"note":"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.","wrong":"app.use(require('strict-transport-security'));","symbol":"HSTS Middleware Application","correct":"app.use(sts.getSTS({'max-age':{'days': 30}}));"},{"note":"The `getSTS` function expects a plain JavaScript object as its argument, containing properties like `max-age`, `includeSubDomains`, and `preload`.","wrong":"sts.getSTS('max-age=...');","symbol":"Configuration Object","correct":"sts.getSTS({'max-age':{'days': 30}, 'includeSubDomains': true, 'preload': true});"}],"quickstart":{"code":"const sts = require('strict-transport-security');\nconst express = require('express');\nconst app = express();\n\nconst globalSTS = sts.getSTS({'max-age':{'days': 30}});\nconst localSTS = sts.getSTS({'max-age':{'days': 10}, 'includeSubDomains': true});\n\n// This will apply this policy to all requests\napp.use(globalSTS);\n\napp.get('/', (req, res) => {\n  res.send('Using global strict transport security policy!');\n});\n\n// This will apply the local policy just to this path, overriding the global policy\napp.get('/local', localSTS, (req, res) => {\n  res.send('Using path local strict transport security policy!');\n});\n\napp.listen(3000, () => {\n  console.log('Example app listening on port 3000!');\n});","lang":"javascript","description":"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."},"warnings":[{"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.","message":"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.","severity":"gotcha","affected_versions":">=0.1.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=0.3.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=0.1.0"}],"env_vars":null,"last_verified":"2026-04-23T00:00:00.000Z","next_check":"2026-07-22T00:00:00.000Z","problems":[{"fix":"Ensure you have an Express or Connect application instance (e.g., `const app = express();`) before calling `app.use()`.","cause":"Attempting to use the middleware without having an initialized Express or Connect application instance.","error":"TypeError: app.use is not a function"},{"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.","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.","error":"TypeError: sts.getSTS is not a function"},{"fix":"The `max-age` option expects an object with a duration property (e.g., `days`, `seconds`), for example: `{'max-age': {'days': 30}}`.","cause":"Incorrect format for the `max-age` option within the `getSTS` configuration object.","error":"Cannot read properties of undefined (reading 'days') or similar configuration error"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}