fix(security,config): remove unimplemented JWT auth-type, close silent downgrade (G-1)

The pre-G-1 config validator accepted CERTCTL_AUTH_TYPE=jwt and the
startup log faithfully echoed 'authentication enabled type=jwt'.
Reasonable people read that and concluded JWT auth was on. It wasn't.
The auth-middleware wiring at cmd/server/main.go unconditionally routed
every request through the api-key bearer middleware regardless of
cfg.Auth.Type. So CERTCTL_AUTH_TYPE=jwt quietly compared the incoming
'Authorization: Bearer <token>' against whatever string the operator put
in CERTCTL_AUTH_SECRET — real JWT clients got 401, and operators who
treated CERTCTL_AUTH_SECRET as a *signing* secret (because they thought
they were configuring JWT) had effectively handed an attacker an api-key.
A security finding masquerading as a config option.

We chose the audit-recommended structural fix: remove the option, fail
fast at startup, and add the gateway-fronting pattern as the documented
forward path. Implementing JWT middleware would have meant jwks vs
static-secret rotation, claim mapping, expiry enforcement, audience and
issuer validation, key rollover semantics, and regression coverage at the
same depth as the existing api-key path — a feature, not a fix. Operators
who genuinely need JWT/OIDC front certctl with an authenticating gateway
(oauth2-proxy / Envoy ext_authz / Traefik ForwardAuth / Pomerium /
Authelia) and run the upstream certctl with CERTCTL_AUTH_TYPE=none. Same
shape works on docker-compose and Helm.

The change is comprehensive across 7 phases — every surface that
mentioned 'jwt' as a certctl-auth-type is updated, plus structural
backstops (typed enum, runtime guard, helm template validation, CI grep
guard) so the lie can't reappear.

Files changed:

Phase 1 — production code (typed enum + jwt removal):
- internal/config/config.go: AuthType typed alias + AuthTypeAPIKey /
  AuthTypeNone constants + ValidAuthTypes() helper. Validate() routes
  literal 'jwt' through a dedicated multi-line diagnostic naming the
  authenticating-gateway pattern, then cross-checks against
  ValidAuthTypes(). Secret-required branch simplified to api-key-only.
  Field comment on AuthConfig.Type rewritten to drop jwt and point at
  the gateway pattern.
- internal/api/middleware/middleware.go: AuthConfig.Type field comment
  references the typed config.AuthType constants.
- internal/api/handler/health.go: same treatment for HealthHandler.AuthType.
- cmd/server/main.go: defense-in-depth runtime switch immediately after
  config.Load() — exits 1 on any unsupported auth-type that bypassed the
  validator. Auth-disabled startup log explicitly names the
  authenticating-gateway pattern.

Phase 2 — tests (Red→Green, contract pinning):
- internal/config/config_test.go: TestValidate_JWTAuth_RejectedDedicated
  (two table rows pinning the dedicated G-1 error fires regardless of
  whether Secret is set), TestValidAuthTypesDoesNotContainJWT (property
  guard against future re-introduction),
  TestValidAuthTypesIsExactly_APIKey_None (allowed-set contract),
  TestValidate_GenericInvalidAuthType (pins non-jwt invalid values still
  hit the generic invalid-auth-type error). Removed the prior
  TestValidate_JWTAuth_MissingSecret happy-path since its premise is
  inverted post-G-1.
- internal/api/handler/health_test.go: removed
  TestAuthInfo_ReturnsAuthType_JWT (which baked the silent-downgrade lie
  into the regression suite). Pre-existing _APIKey test continues to
  cover the api-key happy path.

Phase 3 — spec, docs, env templates:
- api/openapi.yaml: auth_type enum dropped to [api-key, none] with
  inline comment naming the G-1 closure.
- .env.example (root): CERTCTL_AUTH_TYPE comment block rewritten to drop
  jwt and point at the gateway pattern; secret-required conditional
  simplified to api-key-only.
- docs/architecture.md: middleware-stack bullet rewritten to drop the
  JWT mention; new H3 'Authenticating-gateway pattern (JWT, OIDC, mTLS)'
  section explaining the design rationale and listing oauth2-proxy /
  Envoy ext_authz / Traefik ForwardAuth / Pomerium / Authelia / Caddy
  forward_auth / Apache mod_auth_openidc / nginx auth_request as the
  standard fronting options.
- docs/upgrade-to-v2-jwt-removal.md (new ~125 lines): migration guide
  with preconditions, what-changes, both recovery paths, complete
  docker-compose oauth2-proxy walkthrough, Traefik ForwardAuth and Envoy
  ext_authz patterns, rollback posture.

Phase 4 — Helm chart (template validation + docs):
- deploy/helm/certctl/templates/_helpers.tpl: new certctl.validateAuthType
  helper mirroring the existing certctl.tls.required pattern. Fails
  template render on any server.auth.type outside {api-key, none} with
  a multi-line diagnostic.
- deploy/helm/certctl/templates/server-deployment.yaml,
  server-configmap.yaml, server-secret.yaml: invoke the helper at the
  top of each template that depends on .Values.server.auth.type.
- deploy/helm/certctl/values.yaml: auth: block comment expanded with the
  G-1 rationale and gateway-pattern cross-reference.
- deploy/helm/CHART_SUMMARY.md: server.auth.type table row now surfaces
  the allowed set and points at the upgrade doc.
- deploy/helm/certctl/README.md: new 'JWT / OIDC via authenticating
  gateway' section with a Kubernetes-flavored oauth2-proxy + certctl
  walkthrough.

Phase 5 — release surface:
- CHANGELOG.md: new [unreleased] top entry with Breaking / Removed /
  Added / Changed sections; explicit pointer at
  docs/upgrade-to-v2-jwt-removal.md from the Breaking subsection.

Phase 6 — CI guardrail:
- .github/workflows/ci.yml: new 'Forbidden auth-type literal regression
  guard (G-1)' step. Scoped patterns catch the actual regression shapes
  (map literal, slice literal, switch case, OpenAPI enum, env-file
  default, AuthType('jwt') cast). Comments and the dedicated rejection
  branch are intentionally exempt; connector-package JWT references
  (Google OAuth2 / step-ca) are exempt as out-of-scope external
  protocols. Verified locally: the guard passes on the actual tree and
  fires on all 4 synthetic regression patterns.

Out of scope (explicitly untouched):
- internal/connector/discovery/gcpsm/gcpsm.go — Google OAuth2 service-
  account JWT (external protocol).
- internal/connector/issuer/googlecas/googlecas.go — same.
- internal/connector/issuer/stepca/stepca.go — step-ca's provisioner
  one-time-token JWT for /sign API.
- docs/test-env.md, docs/connectors.md, docs/features.md — describe
  external CAs' use of JWT, not certctl's auth shape.
- Implementing actual JWT middleware. Feature, not a fix.

Verification (all gates pass):
- go build ./... — clean
- go vet ./... — clean
- go test -short ./... — every package green
- go test -short -race ./internal/config/... ./internal/api/... — clean
- govulncheck ./... — no vulnerabilities in our code
- helm lint deploy/helm/certctl/ — clean
- helm template with auth.type=api-key — renders OK
- helm template with auth.type=none — renders OK
- helm template with auth.type=jwt — fails with validateAuthType
  diagnostic (exit 1)
- python3 yaml.safe_load on api/openapi.yaml — parses
- CI guardrail mirror — clean on real tree, fires on all 4 synthetic
  regression patterns
- Smoke test: 'CERTCTL_AUTH_TYPE=jwt ./certctl-server' exits non-zero
  with: 'Failed to load configuration: CERTCTL_AUTH_TYPE=jwt is no
  longer accepted (G-1 silent auth downgrade): no JWT middleware ships
  with certctl. To use JWT/OIDC, run an authenticating gateway
  (oauth2-proxy / Envoy ext_authz / Traefik ForwardAuth / Pomerium) in
  front of certctl and set CERTCTL_AUTH_TYPE=none on the upstream.
  See docs/architecture.md "Authenticating-gateway pattern" and
  docs/upgrade-to-v2-jwt-removal.md for the migration walkthrough'

config pkg coverage: ValidAuthTypes 100%, Validate 94.7%, total 75.5%.

Refs: coverage-gap-audit-2026-04-24-v5/unified-audit.md
      §2 P1 cluster, cat-g-jwt_silent_auth_downgrade
      Audit recommendation followed verbatim: 'Remove jwt from
      validAuthTypes until middleware ships'.

internal/config/config.go

@@ -802,13 +802,59 @@ type NamedAPIKey struct {
 	Admin bool
 }
 
+// AuthType is the discriminator for the API auth middleware shape. The
+// string alias preserves env-var roundtrip (the value flows through getEnv
+// as a plain string) while giving us a typed surface for switches and
+// validation. Use the named constants below rather than string literals
+// so future enum additions/removals are caught at compile time.
+//
+// G-1 (P1): the pre-G-1 validAuthTypes map literal accepted "jwt" with no
+// JWT middleware behind it (silent auth downgrade — the configured type
+// was logged as "jwt" but every request routed through the api-key bearer
+// middleware regardless). Operators who set CERTCTL_AUTH_TYPE=jwt thought
+// they had JWT auth; they didn't. The typed alias + ValidAuthTypes()
+// helper make the allowed set the single source of truth across config
+// validation, the runtime defense-in-depth switch in main.go, and the
+// helm-chart template guard (`certctl.validateAuthType`).
+type AuthType string
+
+const (
+	// AuthTypeAPIKey routes requests through the api-key bearer middleware.
+	// CERTCTL_AUTH_SECRET (or CERTCTL_API_KEYS_NAMED) is required.
+	AuthTypeAPIKey AuthType = "api-key"
+
+	// AuthTypeNone disables authentication entirely. Development only —
+	// the server logs a loud Warn at startup. Operators who need
+	// JWT/OIDC/mTLS run an authenticating gateway (oauth2-proxy / Envoy
+	// ext_authz / Traefik ForwardAuth / Pomerium) in front of certctl
+	// and set this value on the upstream certctl process. See
+	// docs/architecture.md "Authenticating-gateway pattern".
+	AuthTypeNone AuthType = "none"
+)
+
+// ValidAuthTypes returns the allowed CERTCTL_AUTH_TYPE values. The set is
+// intentionally narrow — JWT was accepted pre-G-1 with no middleware
+// implementation behind it. Single source of truth referenced by the
+// validator below, the runtime guard in cmd/server/main.go, the helm
+// chart template (`certctl.validateAuthType`), and the property test in
+// config_test.go that pins "jwt" out of the slice forever.
+func ValidAuthTypes() []AuthType {
+	return []AuthType{AuthTypeAPIKey, AuthTypeNone}
+}
+
 // AuthConfig contains authentication configuration.
 type AuthConfig struct {
 	// Type sets the authentication mechanism for the REST API.
-	// Valid values: "api-key" (default, production), "jwt", "none" (development only).
-	// When "api-key", clients must provide Authorization: Bearer <key> header.
-	// "none" requires explicit opt-in via CERTCTL_AUTH_TYPE env var with warning logged.
+	// Valid values: "api-key" (default, production) and "none" (development
+	// only — disables authentication on the API and logs a loud Warn at
+	// startup). For JWT/OIDC, run an authenticating gateway (oauth2-proxy /
+	// Envoy / Traefik ForwardAuth / Pomerium) in front of certctl and set
+	// CERTCTL_AUTH_TYPE=none on the upstream — see docs/architecture.md
+	// "Authenticating-gateway pattern" and docs/upgrade-to-v2-jwt-removal.md.
 	// Setting: CERTCTL_AUTH_TYPE environment variable. Default: "api-key".
+	// Use the AuthType constants (AuthTypeAPIKey / AuthTypeNone) for typed
+	// comparisons; the field stays `string` to preserve env-var roundtrip
+	// shape used by getEnv() and downstream Helm/compose interpolation.
 	Type string
 
 	// Secret is the legacy authentication secret (comma-separated API keys).
@@ -1148,18 +1194,40 @@ func (c *Config) Validate() error {
 		return fmt.Errorf("invalid log format: %s", c.Log.Format)
 	}
 
-	// Validate auth type
-	validAuthTypes := map[string]bool{
-		"api-key": true,
-		"jwt":     true,
-		"none":    true,
+	// Validate auth type.
+	//
+	// G-1 (P1): the pre-G-1 set was {"api-key", "jwt", "none"} with "jwt"
+	// accepted but no JWT middleware shipped — silent auth downgrade.
+	// Post-G-1 we route a literal "jwt" value through a dedicated
+	// rejection that gives operators actionable guidance (the
+	// authenticating-gateway pattern) instead of the generic
+	// "invalid auth type". Then we cross-check against ValidAuthTypes()
+	// so any value outside {api-key, none} surfaces uniformly.
+	if c.Auth.Type == "jwt" {
+		return fmt.Errorf(
+			"CERTCTL_AUTH_TYPE=jwt is no longer accepted (G-1 silent auth " +
+				"downgrade): no JWT middleware ships with certctl. To use " +
+				"JWT/OIDC, run an authenticating gateway (oauth2-proxy / " +
+				"Envoy ext_authz / Traefik ForwardAuth / Pomerium) in " +
+				"front of certctl and set CERTCTL_AUTH_TYPE=none on the " +
+				"upstream. See docs/architecture.md \"Authenticating-" +
+				"gateway pattern\" and docs/upgrade-to-v2-jwt-removal.md " +
+				"for the migration walkthrough")
 	}
-	if !validAuthTypes[c.Auth.Type] {
-		return fmt.Errorf("invalid auth type: %s", c.Auth.Type)
+	authTypeValid := false
+	for _, t := range ValidAuthTypes() {
+		if AuthType(c.Auth.Type) == t {
+			authTypeValid = true
+			break
+		}
+	}
+	if !authTypeValid {
+		return fmt.Errorf("invalid auth type: %s (valid: %v)", c.Auth.Type, ValidAuthTypes())
 	}
 
-	// If using JWT or API-key, secret is required
-	if (c.Auth.Type == "jwt" || c.Auth.Type == "api-key") && c.Auth.Secret == "" {
+	// If using API-key, secret is required. (Secret was previously also
+	// required for "jwt"; removed with the jwt rejection above.)
+	if c.Auth.Type == string(AuthTypeAPIKey) && c.Auth.Secret == "" {
 		return fmt.Errorf("auth secret is required for auth type %s", c.Auth.Type)
 	}