feat(caddy): make (hsts) snippet's Strict-Transport-Security value configurable

[Cre-eD]

Summary

Adds CaddyConfig.HSTSValue *string so operators can override the Strict-Transport-Security value emitted by the embedded (hsts) snippet without forking the snippet definition. When unset, the snippet defaults to the prior literal max-age=31536000; includeSubDomains; preload byte-for-byte — no diff for existing consumers.

Motivation

The snippet's default ships the preload directive. Including preload is a sticky one-way commitment: once a domain is submitted to the HSTS preload list (the static list browsers ship with), removal requires asking the browser vendor and waiting months. Operators may want to relax to max-age=31536000; includeSubDomains (no preload) for the rollout phase, or further during a staged migration, without losing the snippet's other behaviors (HTTP→HTTPS redirect on X-Forwarded-Proto: http).

Implementation

• embed/caddy/Caddyfile — (hsts) snippet now uses Caddy's native env-var placeholder:

  Strict-Transport-Security "{$HSTS_VALUE:max-age=31536000; includeSubDomains; preload}"
  

  Caddy resolves {$VAR:default} at config parse time; the default token extends to the matching }, so spaces and semicolons in the default string survive the parser intact.

• pkg/clouds/k8s/types.go — adds HSTSValue *string to CaddyConfig, documented inline (yaml tag hstsValue,omitempty).

• pkg/clouds/pulumi/kubernetes/caddy.go — when CaddyConfig.HSTSValue != nil, sets the HSTS_VALUE env var on the Caddy container via deploymentConfig.StackConfig.Env. When nil, no env var is added and the Caddyfile placeholder's default kicks in.

• docs/schemas/gcp/gkeautopilotresource.json — schema gains hstsValue: { type: string } so the field is discoverable in tooling.

Tests

• TestCaddyfileEmbedHSTSPlaceholder — asserts the snippet uses the placeholder form (not the prior bare literal). Guards against a refactor silently re-inlining the literal and making HSTSValue inert.
• TestCaddyConfig_HSTSValue_FieldShape — locks the struct contract: *string (nilable so unset = use default), yaml tag hstsValue,omitempty.

Compatibility

• Unset (existing consumers): byte-identical Caddyfile content + no env var added → zero behavioral diff.
• Set: env var lands on the Caddy container; placeholder substitutes at Caddy parse time. The previous deploy's Caddyfile / annotation state is preserved exactly, so no spurious Pulumi diff on stacks that don't opt in.

Caveats / scope

• The env var lives on the parent Caddy aggregator pod, not the per-stack consumer. The value is set once per cluster (via the parent stack's caddy.hstsValue); all sites the aggregator serves get the same HSTS value. Per-site override would require a different mechanism (e.g., per-stack lbConfig.siteExtraHelpers + header_down) and is out of scope here.

Test plan

• go build ./pkg/... + go vet ./pkg/... pass.
• Both regression tests pass.
• CI: full pkg/clouds/pulumi/kubernetes/... suite green.
• Manual: SC preview build → deploy a stack with caddy.hstsValue: "max-age=86400" → curl -sIL <host>/ | grep -i strict-transport-security returns the overridden value, not the default.

[github-actions]

Semgrep Scan Results

Repository: api | Commit: 9ba8f0a

Check	Status	Details
✅ Semgrep	Pass	0 total findings (no error/warning)

Scanned at 2026-05-30 22:49 UTC

[github-actions]

Security Scan Results

Repository: api | Commit: 9ba8f0a

Check	Status	Details
✅ Secret Scan	Pass	No secrets detected
✅ Dependencies (Trivy)	Pass	0 total (no critical/high)
✅ Dependencies (Grype)	Pass	0 total (no critical/high)
📦 SBOM	Generated	527 components (CycloneDX)

Scanned at 2026-05-30 22:49 UTC

[Cre-eD]

End-to-end behavior verified

Built preview v2026.5.44-pre.b7b92fa-preview.b7b92fa. Ran a local Caddy 2.11.3 instance with the exact (hsts) snippet syntax from this PR's embed/caddy/Caddyfile:

(hsts) {
  header {
     Strict-Transport-Security "{$HSTS_VALUE:max-age=31536000; includeSubDomains; preload}"
  }
}

:8080 {
  respond "ok"
  import hsts
}

Three scenarios via docker run … caddy:2.11.3 with different env settings:

HSTS_VALUE env	Response header value
unset	max-age=31536000; includeSubDomains; preload (placeholder default)
"max-age=86400; includeSubDomains"	max-age=86400; includeSubDomains
"" (empty string)	`` (empty — confirms the reviewers' footgun)

The empty-string case is exactly the silent-broken-header scenario the v2 review pass guarded against in caddyHSTSEnv() (v != nil && *v != ""); without that guard, a parent stack setting caddy.hstsValue: "" would ship an empty header. The Go-side helper is also unit-tested across all 5 cases (TestCaddyHSTSEnv_WiringContract).

This is the canonical syntax — Caddy 2.x parses the placeholder, the default token extends across spaces and semicolons unchanged, and the empty-string trap is closed at the SC api layer (not Caddy's).

Ready to merge.