Make the HSTS max-age configurable with HSTS_MAX_AGE (closes #271)

HSTS_MAX_AGE, a Go duration, sets the max-age of the
Strict-Transport-Security header. Unset, it is ten years (87600h);
0 sends no header at all. A negative value, or one that is not a
whole number of seconds, stops startup like an unparseable one.
includeSubDomains and preload stay in the header. The value is shown
on /settings and in the startup log, and the README's HSTS section
now says what each part of the header commits the operator to.

Model: opus-5-5

internal/config/config.go

@@ -68,6 +68,10 @@ const (
 	// authenticated activity before it expires.
 	defaultSessionIdleTimeout = 24 * time.Hour
 
+	// defaultHSTSMaxAge is the max-age of the Strict-Transport-Security
+	// header when HSTS_MAX_AGE is unset: ten years.
+	defaultHSTSMaxAge = 87600 * time.Hour
+
 	// defaultReceiverRateLimit is the default number of requests
 	// per minute each client IP may send to a single webhook
 	// receiver entrypoint. Generous for legitimate webhook
@@ -120,6 +124,10 @@ var ErrInvalidBindAddress = errors.New("invalid bind address")
 // the Sentry SDK cannot parse as a DSN.
 var ErrInvalidSentryDSN = errors.New("invalid Sentry DSN")
 
+// ErrInvalidHSTSMaxAge is returned when HSTS_MAX_AGE is set to a
+// negative duration or one that is not a whole number of seconds.
+var ErrInvalidHSTSMaxAge = errors.New("invalid HSTS max-age")
+
 // ErrDotEnvUnreadable is returned when the optional .env file exists
 // but cannot be read or parsed. A file that is not there is not an
 // error; a file that is there and broken is.
@@ -169,6 +177,10 @@ type Config struct {
 	// which a session expires. Non-positive disables idle expiry.
 	SessionIdleTimeout time.Duration
 
+	// HSTSMaxAge is the max-age of the Strict-Transport-Security
+	// header. Zero means the header is not sent at all.
+	HSTSMaxAge time.Duration
+
 	// ReceiverRateLimit is the number of requests per minute each
 	// client IP may send to a single webhook receiver entrypoint.
 	ReceiverRateLimit int
@@ -624,6 +636,27 @@ func resolveEnvironment() (string, error) {
 	return environment, nil
 }
 
+// resolveHSTSMaxAge reads HSTS_MAX_AGE. Zero is allowed and turns the
+// Strict-Transport-Security header off. A fraction of a second is an
+// error rather than rounded, because the header carries whole seconds
+// and would otherwise say something other than what was set.
+func resolveHSTSMaxAge() (time.Duration, error) {
+	maxAge, err := envDuration("HSTS_MAX_AGE", defaultHSTSMaxAge)
+	if err != nil {
+		return 0, err
+	}
+
+	if maxAge < 0 || maxAge%time.Second != 0 {
+		return 0, fmt.Errorf(
+			"%w: HSTS_MAX_AGE must be zero or a positive whole "+
+				"number of seconds, got %s",
+			ErrInvalidHSTSMaxAge, maxAge,
+		)
+	}
+
+	return maxAge, nil
+}
+
 // resolveListener reads the two variables that describe the HTTP
 // listener: which port it claims and which address it claims it on.
 // They are read together because neither is meaningful alone, and
@@ -684,6 +717,11 @@ func loadFromEnv() (*Config, error) {
 		return nil, err
 	}
 
+	hstsMaxAge, err := resolveHSTSMaxAge()
+	if err != nil {
+		return nil, err
+	}
+
 	receiverRateLimit, err := envPositiveInt(
 		"RECEIVER_RATE_LIMIT",
 		defaultReceiverRateLimit,
@@ -723,6 +761,7 @@ func loadFromEnv() (*Config, error) {
 		SentryDSN:              sentryDSN,
 		RetentionSweepInterval: retentionSweepInterval,
 		SessionIdleTimeout:     sessionIdleTimeout,
+		HSTSMaxAge:             hstsMaxAge,
 		ReceiverRateLimit:      receiverRateLimit,
 		TrustedProxies:         trustedProxies,
 		AllowedEgressCIDRs:     allowedEgressCIDRs,
@@ -807,6 +846,7 @@ func New(lc fx.Lifecycle, params ConfigParams) (*Config, error) {
 		// disables idle expiry entirely, and that is worth showing
 		// back to the operator.
 		"sessionIdleTimeout", s.SessionIdleTimeout.String(),
+		"hstsMaxAge", s.HSTSMaxAge.String(),
 		"receiverRateLimit", s.ReceiverRateLimit,
 		"trustedProxies", len(s.TrustedProxies),
 		"allowedEgressCIDRs", len(s.AllowedEgressCIDRs),

internal/config/config_test.go

@@ -379,6 +379,83 @@ func testSessionIdleTimeoutSuccess(
 	assert.Equal(t, expected, cfg.SessionIdleTimeout)
 }
 
+func TestHSTSMaxAge(t *testing.T) {
+	tests := []struct {
+		name        string
+		set         bool
+		value       string
+		expectError bool
+		// sentinel, when set, must be wrapped by the startup
+		// error; every error case must additionally name the
+		// variable in its message.
+		sentinel error
+		expected time.Duration
+	}{
+		{
+			name:     caseUnsetUsesDefault,
+			set:      false,
+			expected: 87600 * time.Hour,
+		},
+		{
+			name:     caseValidValueParsed,
+			set:      true,
+			value:    "720h",
+			expected: 720 * time.Hour,
+		},
+		{
+			// Zero turns the header off; it is not an error.
+			name:     "zero is accepted",
+			set:      true,
+			value:    "0",
+			expected: 0,
+		},
+		{
+			name:        caseUnparseableFails,
+			set:         true,
+			value:       "10 years",
+			expectError: true,
+		},
+		{
+			// A whole number of seconds, so only the sign is wrong.
+			name:        "negative whole seconds fail startup",
+			set:         true,
+			value:       "-1s",
+			expectError: true,
+			sentinel:    config.ErrInvalidHSTSMaxAge,
+		},
+		{
+			name:        "fraction of a second fails startup",
+			set:         true,
+			value:       "1500ms",
+			expectError: true,
+			sentinel:    config.ErrInvalidHSTSMaxAge,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			// Cannot use t.Parallel() here because t.Setenv
+			// is incompatible with parallel subtests.
+			configtest.ClearEnv(t)
+			t.Setenv("WEBHOOKER_ENVIRONMENT", "dev")
+
+			if tt.set {
+				t.Setenv("HSTS_MAX_AGE", tt.value)
+			}
+
+			if tt.expectError {
+				expectStartupErrorFor(t, "HSTS_MAX_AGE", tt.sentinel)
+
+				return
+			}
+
+			cfg, err := buildConfig(t)
+			require.NoError(t, err)
+			assert.Equal(t, tt.expected, cfg.HSTSMaxAge)
+		})
+	}
+}
+
 func TestDefaultDataDir(t *testing.T) {
 	for _, env := range []string{"", "dev", "prod"} {
 		name := env