Configuration Management System for Runtime Settings

[jamestexas]

Problem

We currently have several hard-coded configuration values that should be runtime-configurable:

1. Request size limit (Finding Documentation cleanup: consolidate status, add security warnings #28 fix): Hard-coded 1MB limit in pkg/http/middleware/signet.go
2. Chunked transfer timeouts: Not yet implemented, will need configuration
3. Clock skew tolerance: Currently hard-coded 30 seconds
4. Token/nonce cleanup intervals: Implementation-specific

As the system grows, we'll need more configuration points (rate limits, cache sizes, etc.). Hard-coding these creates operational friction and requires code changes for tuning.

Proposed Solution

Design and implement a unified configuration management system that:

Requirements

1. Environment variable support - Standard 12-factor app pattern
2. Configuration file support - YAML/TOML for complex setups
3. Runtime updates - Where safe (e.g., log levels), allow hot reload
4. Type safety - Strongly typed config structs with validation
5. Defaults - Sensible defaults for all settings
6. Documentation - Auto-generate config docs from struct tags

Configuration Categories

Security Settings

type SecurityConfig struct {
    MaxRequestSize    int64         `env:"SIGNET_MAX_REQUEST_SIZE" default:"1048576"` // 1MB
    ChunkedTimeout    time.Duration `env:"SIGNET_CHUNKED_TIMEOUT" default:"30s"`
    ClockSkew         time.Duration `env:"SIGNET_CLOCK_SKEW" default:"30s"`
    MaxTokensPerUser  int           `env:"SIGNET_MAX_TOKENS_PER_USER" default:"100"`
}

Storage Settings

type StorageConfig struct {
    TokenStoreType    string        `env:"SIGNET_TOKEN_STORE" default:"memory"`
    NonceStoreType    string        `env:"SIGNET_NONCE_STORE" default:"memory"`
    CleanupInterval   time.Duration `env:"SIGNET_CLEANUP_INTERVAL" default:"5m"`
    RedisURL          string        `env:"SIGNET_REDIS_URL"`
}

Observability Settings

type ObservabilityConfig struct {
    MetricsEnabled    bool          `env:"SIGNET_METRICS_ENABLED" default:"true"`
    LogLevel          string        `env:"SIGNET_LOG_LEVEL" default:"info"`
    TracingEnabled    bool          `env:"SIGNET_TRACING_ENABLED" default:"false"`
}

Implementation Approach

Phase 1: Basic ENV support (Week 1)

• Add github.com/kelseyhightower/envconfig or similar
• Create config structs with validation
• Update middleware to use config values

Phase 2: Config files (Week 2)

• Add YAML/TOML file parsing
• Merge file + env (env wins for overrides)
• Add --config flag to CLI commands

Phase 3: Validation & Docs (Week 3)

• Add comprehensive validation rules
• Auto-generate configuration documentation
• Add config validation command (signet validate-config)

Phase 4: Hot Reload (Future)

• Watch config file for changes
• Reload safe settings without restart
• Emit metrics on config changes

Example Usage

# Environment variables
export SIGNET_MAX_REQUEST_SIZE=2097152  # 2MB
export SIGNET_CLOCK_SKEW=60s
signet authority

# Config file
signet authority --config /etc/signet/config.yaml

# Validation
signet validate-config --config /etc/signet/config.yaml

Testing Strategy

• Unit tests for config parsing and validation
• Integration tests with different config sources
• Test env override priority (file < env < CLI flags)
• Test validation error messages

Related Issues

• Security Finding Documentation cleanup: consolidate status, add security warnings #28: Request size limits (immediate driver)
• Future: Rate limiting, circuit breakers, cache tuning
• Future: Multi-tenancy configuration

Success Criteria

• All hard-coded values moved to configuration
• Environment variable support working
• Config file support working
• Validation catches invalid configs
• Documentation auto-generated
• Backwards compatible with current defaults

Notes

This is a foundational feature that will enable future operational flexibility. While it adds complexity, it's essential for production deployments where different environments need different tuning.

The configuration system should be designed to prevent accidental retroactive breaking changes (retcon) - once a config key is published, maintain backwards compatibility or provide migration path.