feat(middleware): add hsts off-switch to SecurityHeaders (#2174) (#2195)

Adds a boolean `hsts` constructor argument (default `true`) to
`wheels.middleware.SecurityHeaders`. When set to `false`, the middleware
skips emitting `Strict-Transport-Security` entirely, regardless of the
resolved environment or explicit `strictTransportSecurity` value.

This gives apps behind TLS-terminating proxies (load balancers, CDNs)
that already emit HSTS a clean off-switch without having to fall back
to `max-age=0` (which clears browser HSTS memory) or duplicating the
proxy's header.

Defaults to `true` to preserve existing behavior byte-for-byte.

Closes #2174

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: bpamiri

CHANGELOG.md

@@ -48,6 +48,7 @@ All historical references to "CFWheels" in this changelog have been preserved fo
 - Middleware pipeline: closure-based chain running at dispatch level before controller instantiation, route-scoped via `.scope(middleware=[...])` or global via `set(middleware=[...])` (#1924)
 - Rate limiting middleware with `wheels.middleware.RateLimiter` supporting fixed window, sliding window, and token bucket strategies with in-memory and database storage (#1931)
 - SecurityHeaders middleware emits Content-Security-Policy, HSTS, and Permissions-Policy headers (#2036)
+- `hsts` argument on `SecurityHeaders` middleware to suppress the `Strict-Transport-Security` header entirely, for apps behind TLS-terminating proxies that emit HSTS themselves (#2174)
 - Multi-tenant support with per-request datasource switching (#1951)
 
 **Views**

vendor/wheels/middleware/SecurityHeaders.cfc

@@ -17,6 +17,7 @@ component implements="wheels.middleware.MiddlewareInterface" output="false" {
 	 * @referrerPolicy Referrer-Policy value.
 	 * @contentSecurityPolicy Content-Security-Policy value. Empty by default (opt-in) because a restrictive policy can break apps with inline scripts/styles.
 	 * @strictTransportSecurity Strict-Transport-Security value. Auto-defaults to `max-age=31536000; includeSubDomains` in production when not explicitly set.
+	 * @hsts Set to false to suppress the Strict-Transport-Security header entirely, regardless of environment or strictTransportSecurity value. Useful when a TLS-terminating proxy already emits HSTS.
 	 * @permissionsPolicy Permissions-Policy value. Empty by default (opt-in) because it is app-specific.
 	 * @environment Application environment (e.g. "production", "development"). When empty, falls back to application.$wheels.environment if available.
 	 */
@@ -27,6 +28,7 @@ component implements="wheels.middleware.MiddlewareInterface" output="false" {
 		string referrerPolicy = "strict-origin-when-cross-origin",
 		string contentSecurityPolicy = "",
 		string strictTransportSecurity = "",
+		boolean hsts = true,
 		string permissionsPolicy = "",
 		string environment = ""
 	) {
@@ -44,10 +46,14 @@ component implements="wheels.middleware.MiddlewareInterface" output="false" {
 			}
 		}
 
-		// Default HSTS in production when not explicitly configured
-		local.hsts = arguments.strictTransportSecurity;
-		if (!Len(local.hsts) && local.env == "production") {
-			local.hsts = "max-age=31536000; includeSubDomains";
+		// Default HSTS in production when not explicitly configured. When arguments.hsts is false,
+		// skip entirely so the header is not emitted regardless of environment or explicit value.
+		local.hsts = "";
+		if (arguments.hsts) {
+			local.hsts = arguments.strictTransportSecurity;
+			if (!Len(local.hsts) && local.env == "production") {
+				local.hsts = "max-age=31536000; includeSubDomains";
+			}
 		}
 
 		if (Len(arguments.frameOptions)) {

vendor/wheels/tests/specs/middleware/SecurityHeadersSpec.cfc

@@ -130,6 +130,30 @@ component extends="wheels.WheelsTest" {
 					expect(local.mw.$headers()).notToHaveKey("Strict-Transport-Security");
 				});
 
+				it("omits HSTS header when hsts=false even in production", function() {
+					local.mw = new wheels.middleware.SecurityHeaders(
+						environment = "production",
+						hsts = false
+					);
+					expect(local.mw.$headers()).notToHaveKey("Strict-Transport-Security");
+				});
+
+				it("omits HSTS header when hsts=false and explicit strictTransportSecurity provided", function() {
+					local.mw = new wheels.middleware.SecurityHeaders(
+						strictTransportSecurity = "max-age=86400",
+						hsts = false
+					);
+					expect(local.mw.$headers()).notToHaveKey("Strict-Transport-Security");
+				});
+
+				it("defaults hsts=true to preserve legacy production behavior", function() {
+					local.mw = new wheels.middleware.SecurityHeaders(
+						environment = "production"
+					);
+					expect(local.mw.$headers()).toHaveKey("Strict-Transport-Security");
+					expect(local.mw.$headers()["Strict-Transport-Security"]).toBe("max-age=31536000; includeSubDomains");
+				});
+
 			});
 
 			describe("Permissions-Policy", function() {

web/sites/guides/src/content/docs/v4-0-0-snapshot/deployment/security-hardening.mdx

@@ -49,6 +49,7 @@ Verified against `vendor/wheels/middleware/SecurityHeaders.cfc`:
 | `referrerPolicy` | `Referrer-Policy` | `strict-origin-when-cross-origin` | line 27, 63 |
 | `contentSecurityPolicy` | `Content-Security-Policy` | `""` (opt-in) | line 28, 65-67 |
 | `strictTransportSecurity` | `Strict-Transport-Security` | `""` — auto-resolves to `max-age=31536000; includeSubDomains` in production | line 29, 48-51, 68-70 |
+| `hsts` | — | `true` — set to `false` to suppress `Strict-Transport-Security` entirely | new |
 | `permissionsPolicy` | `Permissions-Policy` | `""` (opt-in) | line 30, 71-73 |
 | `environment` | — | `""` — falls back to `application.$wheels.environment` | line 31, 37-45 |
 
@@ -91,8 +92,16 @@ new wheels.middleware.SecurityHeaders(
 )
 ```
 
-<Aside type="caution">
-  **No HSTS off-switch yet.** `SecurityHeaders` has no boolean to disable HSTS entirely. Setting `strictTransportSecurity=""` keeps the production auto-default; setting `"max-age=0"` tells browsers to *clear* HSTS memory, which is worse. The only supported way to suppress the header today is to pass an explicit value that matches your proxy. Tracked in [#2174](https://github.com/wheels-dev/wheels/issues/2174).
+<Aside type="tip">
+  **Suppressing HSTS entirely.** When your TLS-terminating proxy (load balancer, CDN, reverse proxy) already emits `Strict-Transport-Security`, pass `hsts=false` so the app does not emit a competing header:
+
+  ```cfm title="config/settings.cfm"
+  set(middleware = [
+      new wheels.middleware.SecurityHeaders(hsts=false)
+  ]);
+  ```
+
+  `hsts=false` takes precedence over both `strictTransportSecurity` and the production auto-default. Leave `hsts=true` (the default) whenever the app owns the HSTS header.
 </Aside>
 
 ## CSRF protection

web/sites/guides/src/content/docs/v4-0-0-snapshot/upgrading/3x-to-4x.mdx

@@ -65,7 +65,7 @@ Related hardening: wildcard-plus-credentials combinations are now rejected (#205
 
 **CHANGELOG:** `Breaking: HSTS header defaults on in production` (#2081).
 
-The `SecurityHeaders` middleware (#2036) emits `Strict-Transport-Security: max-age=31536000; includeSubDomains` by default in the `production` environment. If you terminate TLS outside the app and do not want HSTS emitted from here, there is currently no clean off-switch — see [#2174](https://github.com/wheels-dev/wheels/issues/2174). The workaround until that lands is to strip `Strict-Transport-Security` at your reverse proxy. `deployment/security-hardening.mdx` covers the configuration knobs that do exist today.
+The `SecurityHeaders` middleware (#2036) emits `Strict-Transport-Security: max-age=31536000; includeSubDomains` by default in the `production` environment. To suppress HSTS emission from the app (e.g., when your load balancer already sets it), pass `hsts=false` to the middleware constructor (#2174). `deployment/security-hardening.mdx` covers the full set of configuration knobs.
 
 ### 3. CSRF key required in production; JWT algorithm validated