Janady13/missionmatch / internal/platform/config/config.go

1// Package config loads and validates the application's runtime configuration. 2// 3// Cloud selection is CONFIGURATION, not code (the cloud-portability mandate): the same binary runs 4// on AWS GovCloud or Azure Government by flipping MM_CLOUD and the provider settings. Nothing here 5// imports a cloud SDK, adapters live behind interfaces in their own packages and are wired in 6// cmd/api from this config. 7package config 8 9import ( 10 "encoding/base64" 11 "encoding/hex" 12 "errors" 13 "fmt" 14 "os" 15 "strconv" 16 "strings" 17) 18 19// Env is the deployment environment. 20type Env string 21 22const ( 23 EnvDevelopment Env = "development" 24 EnvProduction Env = "production" 25) 26 27// Cloud is the target government cloud. Local is for dev (MinIO, self-hosted embeddings, no managed services). 28type Cloud string 29 30const ( 31 CloudLocal Cloud = "local" 32 CloudAWSGovCloud Cloud = "aws_govcloud" 33 CloudAzureGov Cloud = "azure_gov" 34) 35 36// EmbeddingProvider selects the embedding adapter. "fake" is a deterministic offline provider for 37// dev/tests; "openai" is any OpenAI compatible endpoint (self hosted vLLM, the production CUI path, 38// or OpenAI); "bedrock"/"azure_openai" are the managed gov cloud adapters (wired at deploy time). 39type EmbeddingProvider string 40 41const ( 42 ProviderFake EmbeddingProvider = "fake" 43 ProviderOpenAI EmbeddingProvider = "openai" 44 ProviderBedrock EmbeddingProvider = "bedrock" 45 ProviderAzureOpenAI EmbeddingProvider = "azure_openai" 46 // ProviderMegamind routes embeddings through the stateless MEGAMIND inference plane (the typed 47 // inference client to the gateway), the production self hosted path for cleared CUI data. 48 ProviderMegamind EmbeddingProvider = "megamind" 49) 50 51// Embeddings configures the embedding provider. Dimension MUST match the vector(N) column width in 52// the schema (default 384); changing the provider's native dimension is a re-embed migration, not a 53// config flip (STACK_DECISIONS.md §6). 54type Embeddings struct { 55 Provider EmbeddingProvider 56 Endpoint string // base URL for the OpenAI-compatible / Azure endpoint 57 Model string // e.g. "text-embedding-3-large", "amazon.titan-embed-text-v2:0", a local model id 58 Dimension int 59 APIKey string // bearer/api-key; for Bedrock/Azure-Entra the adapter uses cloud credentials instead 60 MegamindURL string // base URL of the MEGAMIND gateway when Provider is "megamind" 61} 62 63// Inference configures the typed client to the stateless MEGAMIND inference plane (embeddings, 64// reranking, generation, faithfulness). The heavy models run out of process on the Apple Silicon 65// cluster; this is the only AI compute the FIPS API binary reaches, over HTTP. URL empty means the AI 66// layer is unconfigured and its routes degrade rather than fail the boot. 67type Inference struct { 68 URL string // MEGAMIND gateway base, reached over Tailscale 69 EmbedModel string // 384 dim embedder (all-minilm or bge-small-en-v1.5) 70 RerankModel string // cross encoder (bge-reranker-v2-m3) or the cosine baseline 71 GenerateModel string // local instruct model (e.g. llama3.1:8b) 72 Dimension int // must match the vector(N) column width 73 TimeoutSeconds int // per request 74 MaxRetries int // additional attempts on a transient failure 75 BreakerTrips int // consecutive failures before the breaker opens 76 BreakerCoolSec int // how long the breaker stays open 77 TeachingEnabled bool // federated craft signal transmission; disabled until multiple live clients exist 78} 79 80// ExtractorProvider selects the Mission Check structured extraction adapter (resume or job description 81// text to proposed fields). "deterministic" is the offline rules plus ontology extractor and the 82// default; an LLM backed provider (self hosted vLLM for CUI in production) is a future addition behind 83// the same port. Extraction runs server side only, so a key here never reaches the browser bundle. 84type ExtractorProvider string 85 86const ( 87 ExtractorDeterministic ExtractorProvider = "deterministic" 88) 89 90// Extraction configures the Mission Check structured extraction provider. Endpoint, Model, and APIKey 91// are reserved for a future provider backed extractor and are unused by the deterministic one. 92type Extraction struct { 93 Provider ExtractorProvider 94 Endpoint string 95 Model string 96 APIKey string 97} 98 99// Auth holds the server side secrets and tunables for the authentication module. Every secret here 100// loads from the environment (the root owned secrets file), never the repo or the browser bundle. 101type Auth struct { 102 PepperVersion int // active credential pepper version stored on new credentials 103 Pepper []byte // active credential pepper key (HMAC applied before PBKDF2) 104 PepperPrevious []byte // optional prior pepper key (version PepperVersion minus 1) for rotation 105 TOTPKEKVersion int // active TOTP secret KEK version 106 TOTPKEK []byte // 32 byte AES 256 key encrypting TOTP secrets at rest 107 TOTPKEKPrevious []byte // optional prior TOTP KEK (version TOTPKEKVersion minus 1) so a rotated KEK still decrypts older secrets 108 CSRFKey []byte // HMAC key binding a CSRF token to its session 109 RecoveryLookupKey []byte // HMAC key for recovery code lookup tags 110 TOTPIssuer string // issuer shown in the authenticator app 111 SessionIdleSeconds int // idle timeout (NIST 800-171 3.1.11 default 900) 112 SessionAbsoluteSeconds int // absolute session cap (default 43200, 12 hours) 113 PendingAbsoluteSeconds int // auth_pending (pre MFA) session cap (default 300) 114 InviteExpirySeconds int // invite and activation link lifetime (default 259200, 72 hours) 115 CookieSecure bool // Secure attribute on the session cookie (true except plain http dev) 116 MFARequired bool // when false, login mints an active session after password with no TOTP step (pilot only, forbidden in production) 117} 118 119// Config is the fully-resolved, validated application configuration. 120type Config struct { 121 Env Env 122 HTTPAddr string 123 AppDatabaseURL string // NOBYPASSRLS app role DSN 124 MigratorDatabaseURL string // BYPASSRLS migrator role DSN (used by goose only) 125 ComplianceDatabaseURL string // compliance role DSN, the only path that reads the eeo schema; empty disables adverse impact reporting (503) 126 DecisionRetentionDays int // retention window for identifiable screening artifacts after a decision (default 90) 127 Cloud Cloud 128 Embeddings Embeddings 129 Inference Inference 130 Extraction Extraction 131 RequireFIPS bool // when true, cmd/api aborts unless crypto/fips140.Enabled() 132 AllowDevHeaderAuth bool // dev only X-Org-ID resolver toggle; MUST be false in production 133 AllowedOrigins []string // CSRF Origin allowlist for unsafe verbs; empty disables the check (dev) 134 TrustedProxyHeader string // header carrying the real client IP (set by a trusted reverse proxy); empty uses the TCP peer 135 Auth Auth 136} 137 138// Load reads configuration from the environment, applies defaults, and validates it. 139func Load() (Config, error) { 140 // Secret key decode errors are collected and surfaced alongside validation errors, so a 141 // misconfigured deploy sees every problem at once instead of one boot failure at a time. 142 var secretErrs []error 143 getB := func(key string) []byte { 144 b, err := getBytes(key) 145 if err != nil { 146 secretErrs = append(secretErrs, err) 147 } 148 return b 149 } 150 c := Config{ 151 Env: Env(getDefault("MM_ENV", string(EnvDevelopment))), 152 HTTPAddr: getDefault("MM_HTTP_ADDR", ":8080"), 153 AppDatabaseURL: os.Getenv("MM_DATABASE_URL"), 154 MigratorDatabaseURL: os.Getenv("MM_MIGRATOR_DATABASE_URL"), 155 ComplianceDatabaseURL: os.Getenv("MM_COMPLIANCE_DATABASE_URL"), 156 DecisionRetentionDays: getInt("MM_DECISION_RETENTION_DAYS", 90), 157 Cloud: Cloud(getDefault("MM_CLOUD", string(CloudLocal))), 158 Embeddings: Embeddings{ 159 Provider: EmbeddingProvider(getDefault("MM_EMBED_PROVIDER", string(ProviderFake))), 160 Endpoint: os.Getenv("MM_EMBED_ENDPOINT"), 161 Model: os.Getenv("MM_EMBED_MODEL"), 162 Dimension: getInt("MM_EMBED_DIMENSION", 384), 163 APIKey: os.Getenv("MM_EMBED_API_KEY"), 164 MegamindURL: os.Getenv("MM_MEGAMIND_URL"), 165 }, 166 Inference: Inference{ 167 URL: os.Getenv("MM_MEGAMIND_URL"), 168 EmbedModel: getDefault("MM_MEGAMIND_EMBED_MODEL", "all-minilm"), 169 RerankModel: getDefault("MM_MEGAMIND_RERANK_MODEL", "bge-reranker-v2-m3"), 170 GenerateModel: getDefault("MM_MEGAMIND_GENERATE_MODEL", "llama3.1:8b"), 171 Dimension: getInt("MM_EMBED_DIMENSION", 384), 172 TimeoutSeconds: getInt("MM_MEGAMIND_TIMEOUT_SECONDS", 30), 173 MaxRetries: getInt("MM_MEGAMIND_MAX_RETRIES", 2), 174 BreakerTrips: getInt("MM_MEGAMIND_BREAKER_TRIPS", 5), 175 BreakerCoolSec: getInt("MM_MEGAMIND_BREAKER_COOL_SECONDS", 30), 176 TeachingEnabled: getBool("MM_MEGAMIND_TEACHING_ENABLED", false), 177 }, 178 Extraction: Extraction{ 179 Provider: ExtractorProvider(getDefault("MM_EXTRACT_PROVIDER", string(ExtractorDeterministic))), 180 Endpoint: os.Getenv("MM_EXTRACT_ENDPOINT"), 181 Model: os.Getenv("MM_EXTRACT_MODEL"), 182 APIKey: os.Getenv("MM_EXTRACT_API_KEY"), 183 }, 184 RequireFIPS: getBool("MM_REQUIRE_FIPS", false), 185 AllowDevHeaderAuth: getBool("MM_ALLOW_DEV_HEADER_AUTH", false), 186 AllowedOrigins: splitCSV(os.Getenv("MM_ALLOWED_ORIGINS")), 187 TrustedProxyHeader: os.Getenv("MM_TRUSTED_PROXY_HEADER"), 188 Auth: Auth{ 189 PepperVersion: getInt("MM_CREDENTIAL_PEPPER_VERSION", 1), 190 Pepper: getB("MM_CREDENTIAL_PEPPER"), 191 PepperPrevious: getB("MM_CREDENTIAL_PEPPER_PREVIOUS"), 192 TOTPKEKVersion: getInt("MM_TOTP_KEK_VERSION", 1), 193 TOTPKEK: getB("MM_TOTP_KEK"), 194 TOTPKEKPrevious: getB("MM_TOTP_KEK_PREVIOUS"), 195 CSRFKey: getB("MM_CSRF_KEY"), 196 RecoveryLookupKey: getB("MM_RECOVERY_LOOKUP_KEY"), 197 TOTPIssuer: getDefault("MM_TOTP_ISSUER", "missionMATCH"), 198 SessionIdleSeconds: getInt("MM_SESSION_IDLE_SECONDS", 900), 199 SessionAbsoluteSeconds: getInt("MM_SESSION_ABSOLUTE_SECONDS", 43200), 200 PendingAbsoluteSeconds: getInt("MM_SESSION_PENDING_SECONDS", 300), 201 InviteExpirySeconds: getInt("MM_INVITE_EXPIRY_SECONDS", 259200), 202 CookieSecure: getBool("MM_COOKIE_SECURE", true), 203 MFARequired: getBool("MM_MFA_REQUIRED", true), 204 }, 205 } 206 if err := c.Validate(); err != nil { 207 secretErrs = append(secretErrs, err) 208 } 209 if len(secretErrs) > 0 { 210 return Config{}, errors.Join(secretErrs...) 211 } 212 return c, nil 213} 214 215// Validate enforces invariants and environment-specific requirements. Errors are joined so a 216// misconfigured deploy surfaces every problem at once. 217func (c Config) Validate() error { 218 var errs []error 219 220 switch c.Env { 221 case EnvDevelopment, EnvProduction: 222 default: 223 errs = append(errs, fmt.Errorf("MM_ENV %q invalid (want development|production)", c.Env)) 224 } 225 switch c.Cloud { 226 case CloudLocal, CloudAWSGovCloud, CloudAzureGov: 227 default: 228 errs = append(errs, fmt.Errorf("MM_CLOUD %q invalid (want local|aws_govcloud|azure_gov)", c.Cloud)) 229 } 230 switch c.Embeddings.Provider { 231 case ProviderFake, ProviderOpenAI, ProviderBedrock, ProviderAzureOpenAI, ProviderMegamind: 232 default: 233 errs = append(errs, fmt.Errorf("MM_EMBED_PROVIDER %q invalid", c.Embeddings.Provider)) 234 } 235 if c.Embeddings.Dimension <= 0 { 236 errs = append(errs, errors.New("MM_EMBED_DIMENSION must be > 0")) 237 } 238 // Empty selects the deterministic extractor (the same default extraction.New applies), so a Config 239 // built without an explicit provider validates. 240 switch c.Extraction.Provider { 241 case ExtractorDeterministic, "": 242 default: 243 errs = append(errs, fmt.Errorf("MM_EXTRACT_PROVIDER %q invalid (want deterministic)", c.Extraction.Provider)) 244 } 245 246 // OpenAI-compatible providers need an endpoint + model. 247 if c.Embeddings.Provider == ProviderOpenAI || c.Embeddings.Provider == ProviderAzureOpenAI { 248 if c.Embeddings.Endpoint == "" { 249 errs = append(errs, fmt.Errorf("MM_EMBED_ENDPOINT required for provider %q", c.Embeddings.Provider)) 250 } 251 if c.Embeddings.Model == "" { 252 errs = append(errs, fmt.Errorf("MM_EMBED_MODEL required for provider %q", c.Embeddings.Provider)) 253 } 254 } 255 // The MEGAMIND provider needs the gateway URL and the embed model name. 256 if c.Embeddings.Provider == ProviderMegamind { 257 if c.Embeddings.MegamindURL == "" { 258 errs = append(errs, errors.New("MM_MEGAMIND_URL required for provider \"megamind\"")) 259 } 260 if c.Embeddings.Model == "" && c.Inference.EmbedModel == "" { 261 errs = append(errs, errors.New("MM_EMBED_MODEL or MM_MEGAMIND_EMBED_MODEL required for provider \"megamind\"")) 262 } 263 } 264 265 // TOTP secrets are AES 256, so the KEK must be exactly 32 bytes whenever it is set, in any env. 266 if len(c.Auth.TOTPKEK) != 0 && len(c.Auth.TOTPKEK) != 32 { 267 errs = append(errs, errors.New("MM_TOTP_KEK must decode to exactly 32 bytes (AES 256)")) 268 } 269 if len(c.Auth.TOTPKEKPrevious) != 0 && len(c.Auth.TOTPKEKPrevious) != 32 { 270 errs = append(errs, errors.New("MM_TOTP_KEK_PREVIOUS must decode to exactly 32 bytes (AES 256)")) 271 } 272 if c.Auth.PepperVersion <= 0 { 273 errs = append(errs, errors.New("MM_CREDENTIAL_PEPPER_VERSION must be positive")) 274 } 275 if c.Auth.SessionIdleSeconds <= 0 || c.Auth.SessionAbsoluteSeconds <= 0 || c.Auth.PendingAbsoluteSeconds <= 0 { 276 errs = append(errs, errors.New("session timeout seconds must all be positive")) 277 } 278 if c.DecisionRetentionDays <= 0 { 279 errs = append(errs, errors.New("MM_DECISION_RETENTION_DAYS must be positive")) 280 } 281 282 if c.Env == EnvProduction { 283 if c.AppDatabaseURL == "" { 284 errs = append(errs, errors.New("MM_DATABASE_URL required in production")) 285 } 286 if c.Embeddings.Provider == ProviderFake { 287 errs = append(errs, errors.New("the fake embedding provider must not be used in production")) 288 } 289 if c.Cloud == CloudLocal { 290 errs = append(errs, errors.New("MM_CLOUD must be a government cloud in production")) 291 } 292 // The dev X-Org-ID resolver may never be the production tenant source. 293 if c.AllowDevHeaderAuth { 294 errs = append(errs, errors.New("MM_ALLOW_DEV_HEADER_AUTH must be false in production")) 295 } 296 // FIPS must be enforced, not optional, so the validated crypto path is the one that runs. 297 if !c.RequireFIPS { 298 errs = append(errs, errors.New("MM_REQUIRE_FIPS must be true in production")) 299 } 300 // Every auth secret must be present so the validated crypto has its keys. 301 if len(c.Auth.Pepper) == 0 { 302 errs = append(errs, errors.New("MM_CREDENTIAL_PEPPER required in production")) 303 } 304 if len(c.Auth.TOTPKEK) != 32 { 305 errs = append(errs, errors.New("MM_TOTP_KEK (32 byte AES 256 key) required in production")) 306 } 307 if len(c.Auth.CSRFKey) == 0 { 308 errs = append(errs, errors.New("MM_CSRF_KEY required in production")) 309 } 310 if len(c.Auth.RecoveryLookupKey) == 0 { 311 errs = append(errs, errors.New("MM_RECOVERY_LOOKUP_KEY required in production")) 312 } 313 // The CSRF Origin allowlist must be enforced; an empty list disables it (a dev only path). 314 if len(c.AllowedOrigins) == 0 { 315 errs = append(errs, errors.New("MM_ALLOWED_ORIGINS required in production (the CSRF Origin allowlist must be enforced)")) 316 } 317 // Both cookies use the __Host- prefix, which a browser only accepts when Secure is set; a non 318 // Secure production deploy silently breaks all auth and exposes the token. 319 if !c.Auth.CookieSecure { 320 errs = append(errs, errors.New("MM_COOKIE_SECURE must be true in production (the __Host- cookie prefix requires Secure)")) 321 } 322 // MFA is mandatory in production. The pilot only password only relaxation can never ship to a 323 // government cloud, so a production deploy with it set is a hard configuration error. 324 if !c.Auth.MFARequired { 325 errs = append(errs, errors.New("MM_MFA_REQUIRED must be true in production (MFA is mandatory)")) 326 } 327 } 328 329 return errors.Join(errs...) 330} 331 332// IsProduction reports whether this is a production deployment. 333func (c Config) IsProduction() bool { return c.Env == EnvProduction } 334 335func getDefault(key, def string) string { 336 if v := strings.TrimSpace(os.Getenv(key)); v != "" { 337 return v 338 } 339 return def 340} 341 342func getInt(key string, def int) int { 343 if v := strings.TrimSpace(os.Getenv(key)); v != "" { 344 if n, err := strconv.Atoi(v); err == nil { 345 return n 346 } 347 } 348 return def 349} 350 351func getBool(key string, def bool) bool { 352 if v := strings.TrimSpace(os.Getenv(key)); v != "" { 353 if b, err := strconv.ParseBool(v); err == nil { 354 return b 355 } 356 } 357 return def 358} 359 360// splitCSV splits a comma separated env value into trimmed, non empty entries. 361func splitCSV(v string) []string { 362 if strings.TrimSpace(v) == "" { 363 return nil 364 } 365 parts := strings.Split(v, ",") 366 out := make([]string, 0, len(parts)) 367 for _, p := range parts { 368 if t := strings.TrimSpace(p); t != "" { 369 out = append(out, t) 370 } 371 } 372 return out 373} 374 375// getBytes loads a secret key from the environment using an EXPLICIT encoding prefix so the key 376// material is never ambiguous: "base64:", "hex:", or "raw:". A bare value (no prefix) is decoded as 377// standard base64, and a decode failure is a hard error rather than a silent fall back to the raw 378// string. The silent fall back was a real footgun: a passphrase that happens to be valid base64 would 379// be decoded to different bytes than the operator intended, so the same variable could mean two 380// different keys in two contexts (a TOTP KEK that no longer decrypts its secrets, a pepper that no 381// longer verifies its passwords). Forcing the operator to declare the encoding removes that class of 382// bug. An unset variable yields nil with no error. 383func getBytes(key string) ([]byte, error) { 384 v := strings.TrimSpace(os.Getenv(key)) 385 if v == "" { 386 return nil, nil 387 } 388 switch { 389 case strings.HasPrefix(v, "raw:"): 390 return []byte(strings.TrimPrefix(v, "raw:")), nil 391 case strings.HasPrefix(v, "hex:"): 392 b, err := hex.DecodeString(strings.TrimPrefix(v, "hex:")) 393 if err != nil { 394 return nil, fmt.Errorf("%s: invalid hex value: %w", key, err) 395 } 396 return b, nil 397 case strings.HasPrefix(v, "base64:"): 398 b, err := base64.StdEncoding.DecodeString(strings.TrimPrefix(v, "base64:")) 399 if err != nil { 400 return nil, fmt.Errorf("%s: invalid base64 value: %w", key, err) 401 } 402 return b, nil 403 default: 404 b, err := base64.StdEncoding.DecodeString(v) 405 if err != nil { 406 return nil, fmt.Errorf("%s: value must be base64, or carry a raw: / hex: / base64: prefix: %w", key, err) 407 } 408 return b, nil 409 } 410} 411