1. Three ResponseWriter Wrapper Types With Overlapping Purpose

Severity: Medium | Estimated effort: 1–2 hours

There are three separate http.ResponseWriter wrapper structs that capture HTTP status codes:

The server and tracing variants already embed httputil.BaseResponseWriter, so the core duplication is resolved. However, statusResponseWriter in internal/tracing/http.go is an unnamed, unexported struct defined inline in the file. For clarity it should either be documented or folded into BaseResponseWriter if its sole behaviour is identical (it is: no additional methods beyond the embedding).

Recommendation: Document the design intent at the top of httputil/response_writer.go stating it is the canonical base. Confirm statusResponseWriter adds no behaviour beyond the embed (it doesn't) and consider whether it can be replaced with a direct BaseResponseWriter embed at the call site in tracing/http.go.

2. TLS Helper Functions Scattered Across Four Packages

Severity: Medium | Estimated effort: 2–3 hours

TLS-related helper functions are spread across four distinct locations:

internal/httputil/tls.go
  NewServerTLSConfig(cert tls.Certificate) *tls.Config
  NewClientTLSConfig() *tls.Config

internal/server/gateway_tls.go
  LoadGatewayTLS(certPath, keyPath, caPath string) (*tls.Config, error)

internal/proxy/tls.go
  GenerateSelfSignedTLS(dir string) (*TLSConfig, error)
  writePEM(path, blockType string, derBytes []byte, perm os.FileMode) error

internal/cmd/proxy.go
  configureTLSTrustEnvironment(caCertPath string) error

The four locations have distinct concerns (generic config builders, gateway-level loading, self-signed cert generation, trust store configuration) but a developer looking for "where does TLS live?" will need to check four packages. The writePEM helper in proxy/tls.go is an implementation detail of GenerateSelfSignedTLS and does not belong in a shared location — that's fine. The concern is discoverability.

Recommendation: Add a package-level comment to internal/httputil/tls.go pointing to server/gateway_tls.go and proxy/tls.go for the higher-level functions. Alternatively, consider whether GenerateSelfSignedTLS belongs in httputil since it's a generic TLS utility that happens to be used by the proxy. No move is strictly required; documentation is sufficient.

3. FormatSessionIDForLog Lives in a Separate One-Function File

Severity: Low | Estimated effort: 30 minutes

internal/util/session.go contains a single function:

func FormatSessionIDForLog(sessionID string) string

This function calls Truncate from the same package. It is a formatting utility and fits naturally into internal/util/format_duration.go (which already houses FormatFutureTime and FormatDuration) or a new internal/util/format.go. Having a file with a single 10-line function creates unnecessary file-count overhead.

Recommendation: Move FormatSessionIDForLog into internal/util/format_duration.go (or rename that file to format.go to reflect its broader formatting scope) and delete session.go.

4. config/config_env.go Partially Duplicates envutil.GetEnvInt

Severity: Low | Estimated effort: 1 hour

internal/config/config_env.go defines a package-private helper:

func parseAndValidateIntEnv(envKey string, validate func(int) *ValidationError) (int, bool, error)

This is a thin wrapper over envutil.GetEnvIntRaw that adds domain-specific validation. The pattern is sound (config validation belongs in the config package). However, the function name and shape are very similar to envutil.GetEnvInt, envutil.GetEnvIntRaw, and envutil.GetEnvDuration. A developer new to the codebase may implement a fourth version elsewhere.

Recommendation: Add a comment to parseAndValidateIntEnv (and its sibling GetGatewayPortFromEnv etc.) explaining that the config-level functions intentionally wrap envutil with domain validation. This is a documentation-only change.

5. cmd/proxy.go::configureTLSTrustEnvironment Is an Outlier in a Command File

Severity: Low | Estimated effort: 30 minutes

internal/cmd/proxy.go contains:

func configureTLSTrustEnvironment(caCertPath string) error

This function manipulates the system TLS trust store — it's an infrastructure utility, not a CLI-command-handler concern. It does not depend on any cobra.Command state. It would be more discoverable in internal/httputil/tls.go or internal/proxy/tls.go.

Recommendation: Move configureTLSTrustEnvironment to internal/httputil/tls.go and update the call site in cmd/proxy.go. This improves discoverability and keeps the command file focused on wiring flags to behavior.

6. logger/fileutil.go::atomicWriteFile Could Be Shared More Broadly

Severity: Low | Estimated effort: 1 hour

internal/logger/fileutil.go defines:

func atomicWriteFile(filePath string, data []byte, perm os.FileMode) error
func writeJSONToFile(logDir, fileName string, data any, perm os.FileMode) error

These are currently unexported logger internals, but atomicWriteFile is a general-purpose utility. It is only used within the logger package. If any future package needs atomic file writes, it would either duplicate the logic or depend on internal/logger (creating an awkward dependency). Consider exporting or relocating it.

Recommendation: Export atomicWriteFile as logger.AtomicWriteFile or move it to a new internal/fileutil package if/when a second consumer appears. No immediate action required; flag for the next new use case.