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 // bge-small-en-v1.5 (384 dim) is the production embedder, served on Ollama as the qllama handle. 169 // Stored and query vectors MUST use the same model: switching the model requires a FULL re 170 // backfill (existing vectors from another model are incompatible), see DEPLOY_PLAN.md. 171 EmbedModel: getDefault("MM_MEGAMIND_EMBED_MODEL", "qllama/bge-small-en-v1.5"), 172 RerankModel: getDefault("MM_MEGAMIND_RERANK_MODEL", "bge-reranker-v2-m3"), 173 GenerateModel: getDefault("MM_MEGAMIND_GENERATE_MODEL", "llama3.1:8b"), 174 Dimension: getInt("MM_EMBED_DIMENSION", 384), 175 TimeoutSeconds: getInt("MM_MEGAMIND_TIMEOUT_SECONDS", 30), 176 MaxRetries: getInt("MM_MEGAMIND_MAX_RETRIES", 2), 177 BreakerTrips: getInt("MM_MEGAMIND_BREAKER_TRIPS", 5), 178 BreakerCoolSec: getInt("MM_MEGAMIND_BREAKER_COOL_SECONDS", 30), 179 TeachingEnabled: getBool("MM_MEGAMIND_TEACHING_ENABLED", false), 180 }, 181 Extraction: Extraction{ 182 Provider: ExtractorProvider(getDefault("MM_EXTRACT_PROVIDER", string(ExtractorDeterministic))), 183 Endpoint: os.Getenv("MM_EXTRACT_ENDPOINT"), 184 Model: os.Getenv("MM_EXTRACT_MODEL"), 185 APIKey: os.Getenv("MM_EXTRACT_API_KEY"), 186 }, 187 RequireFIPS: getBool("MM_REQUIRE_FIPS", false), 188 AllowDevHeaderAuth: getBool("MM_ALLOW_DEV_HEADER_AUTH", false), 189 AllowedOrigins: splitCSV(os.Getenv("MM_ALLOWED_ORIGINS")), 190 TrustedProxyHeader: os.Getenv("MM_TRUSTED_PROXY_HEADER"), 191 Auth: Auth{ 192 PepperVersion: getInt("MM_CREDENTIAL_PEPPER_VERSION", 1), 193 Pepper: getB("MM_CREDENTIAL_PEPPER"), 194 PepperPrevious: getB("MM_CREDENTIAL_PEPPER_PREVIOUS"), 195 TOTPKEKVersion: getInt("MM_TOTP_KEK_VERSION", 1), 196 TOTPKEK: getB("MM_TOTP_KEK"), 197 TOTPKEKPrevious: getB("MM_TOTP_KEK_PREVIOUS"), 198 CSRFKey: getB("MM_CSRF_KEY"), 199 RecoveryLookupKey: getB("MM_RECOVERY_LOOKUP_KEY"), 200 TOTPIssuer: getDefault("MM_TOTP_ISSUER", "missionMATCH"), 201 SessionIdleSeconds: getInt("MM_SESSION_IDLE_SECONDS", 900), 202 SessionAbsoluteSeconds: getInt("MM_SESSION_ABSOLUTE_SECONDS", 43200), 203 PendingAbsoluteSeconds: getInt("MM_SESSION_PENDING_SECONDS", 300), 204 InviteExpirySeconds: getInt("MM_INVITE_EXPIRY_SECONDS", 259200), 205 CookieSecure: getBool("MM_COOKIE_SECURE", true), 206 MFARequired: getBool("MM_MFA_REQUIRED", true), 207 }, 208 } 209 if err := c.Validate(); err != nil { 210 secretErrs = append(secretErrs, err) 211 } 212 if len(secretErrs) > 0 { 213 return Config{}, errors.Join(secretErrs...) 214 } 215 return c, nil 216} 217 218// Validate enforces invariants and environment-specific requirements. Errors are joined so a 219// misconfigured deploy surfaces every problem at once. 220func (c Config) Validate() error { 221 var errs []error 222 223 switch c.Env { 224 case EnvDevelopment, EnvProduction: 225 default: 226 errs = append(errs, fmt.Errorf("MM_ENV %q invalid (want development|production)", c.Env)) 227 } 228 switch c.Cloud { 229 case CloudLocal, CloudAWSGovCloud, CloudAzureGov: 230 default: 231 errs = append(errs, fmt.Errorf("MM_CLOUD %q invalid (want local|aws_govcloud|azure_gov)", c.Cloud)) 232 } 233 switch c.Embeddings.Provider { 234 case ProviderFake, ProviderOpenAI, ProviderBedrock, ProviderAzureOpenAI, ProviderMegamind: 235 default: 236 errs = append(errs, fmt.Errorf("MM_EMBED_PROVIDER %q invalid", c.Embeddings.Provider)) 237 } 238 if c.Embeddings.Dimension <= 0 { 239 errs = append(errs, errors.New("MM_EMBED_DIMENSION must be > 0")) 240 } 241 // Empty selects the deterministic extractor (the same default extraction.New applies), so a Config 242 // built without an explicit provider validates. 243 switch c.Extraction.Provider { 244 case ExtractorDeterministic, "": 245 default: 246 errs = append(errs, fmt.Errorf("MM_EXTRACT_PROVIDER %q invalid (want deterministic)", c.Extraction.Provider)) 247 } 248 249 // OpenAI-compatible providers need an endpoint + model. 250 if c.Embeddings.Provider == ProviderOpenAI || c.Embeddings.Provider == ProviderAzureOpenAI { 251 if c.Embeddings.Endpoint == "" { 252 errs = append(errs, fmt.Errorf("MM_EMBED_ENDPOINT required for provider %q", c.Embeddings.Provider)) 253 } 254 if c.Embeddings.Model == "" { 255 errs = append(errs, fmt.Errorf("MM_EMBED_MODEL required for provider %q", c.Embeddings.Provider)) 256 } 257 } 258 // The MEGAMIND provider needs the gateway URL and the embed model name. 259 if c.Embeddings.Provider == ProviderMegamind { 260 if c.Embeddings.MegamindURL == "" { 261 errs = append(errs, errors.New("MM_MEGAMIND_URL required for provider \"megamind\"")) 262 } 263 if c.Embeddings.Model == "" && c.Inference.EmbedModel == "" { 264 errs = append(errs, errors.New("MM_EMBED_MODEL or MM_MEGAMIND_EMBED_MODEL required for provider \"megamind\"")) 265 } 266 } 267 268 // TOTP secrets are AES 256, so the KEK must be exactly 32 bytes whenever it is set, in any env. 269 if len(c.Auth.TOTPKEK) != 0 && len(c.Auth.TOTPKEK) != 32 { 270 errs = append(errs, errors.New("MM_TOTP_KEK must decode to exactly 32 bytes (AES 256)")) 271 } 272 if len(c.Auth.TOTPKEKPrevious) != 0 && len(c.Auth.TOTPKEKPrevious) != 32 { 273 errs = append(errs, errors.New("MM_TOTP_KEK_PREVIOUS must decode to exactly 32 bytes (AES 256)")) 274 } 275 if c.Auth.PepperVersion <= 0 { 276 errs = append(errs, errors.New("MM_CREDENTIAL_PEPPER_VERSION must be positive")) 277 } 278 if c.Auth.SessionIdleSeconds <= 0 || c.Auth.SessionAbsoluteSeconds <= 0 || c.Auth.PendingAbsoluteSeconds <= 0 { 279 errs = append(errs, errors.New("session timeout seconds must all be positive")) 280 } 281 if c.DecisionRetentionDays <= 0 { 282 errs = append(errs, errors.New("MM_DECISION_RETENTION_DAYS must be positive")) 283 } 284 285 if c.Env == EnvProduction { 286 if c.AppDatabaseURL == "" { 287 errs = append(errs, errors.New("MM_DATABASE_URL required in production")) 288 } 289 if c.Embeddings.Provider == ProviderFake { 290 errs = append(errs, errors.New("the fake embedding provider must not be used in production")) 291 } 292 if c.Cloud == CloudLocal { 293 errs = append(errs, errors.New("MM_CLOUD must be a government cloud in production")) 294 } 295 // The dev X-Org-ID resolver may never be the production tenant source. 296 if c.AllowDevHeaderAuth { 297 errs = append(errs, errors.New("MM_ALLOW_DEV_HEADER_AUTH must be false in production")) 298 } 299 // FIPS must be enforced, not optional, so the validated crypto path is the one that runs. 300 if !c.RequireFIPS { 301 errs = append(errs, errors.New("MM_REQUIRE_FIPS must be true in production")) 302 } 303 // Every auth secret must be present so the validated crypto has its keys. 304 if len(c.Auth.Pepper) == 0 { 305 errs = append(errs, errors.New("MM_CREDENTIAL_PEPPER required in production")) 306 } 307 if len(c.Auth.TOTPKEK) != 32 { 308 errs = append(errs, errors.New("MM_TOTP_KEK (32 byte AES 256 key) required in production")) 309 } 310 if len(c.Auth.CSRFKey) == 0 { 311 errs = append(errs, errors.New("MM_CSRF_KEY required in production")) 312 } 313 if len(c.Auth.RecoveryLookupKey) == 0 { 314 errs = append(errs, errors.New("MM_RECOVERY_LOOKUP_KEY required in production")) 315 } 316 // The CSRF Origin allowlist must be enforced; an empty list disables it (a dev only path). 317 if len(c.AllowedOrigins) == 0 { 318 errs = append(errs, errors.New("MM_ALLOWED_ORIGINS required in production (the CSRF Origin allowlist must be enforced)")) 319 } 320 // Both cookies use the __Host- prefix, which a browser only accepts when Secure is set; a non 321 // Secure production deploy silently breaks all auth and exposes the token. 322 if !c.Auth.CookieSecure { 323 errs = append(errs, errors.New("MM_COOKIE_SECURE must be true in production (the __Host- cookie prefix requires Secure)")) 324 } 325 // MFA is mandatory in production. The pilot only password only relaxation can never ship to a 326 // government cloud, so a production deploy with it set is a hard configuration error. 327 if !c.Auth.MFARequired { 328 errs = append(errs, errors.New("MM_MFA_REQUIRED must be true in production (MFA is mandatory)")) 329 } 330 } 331 332 return errors.Join(errs...) 333} 334 335// IsProduction reports whether this is a production deployment. 336func (c Config) IsProduction() bool { return c.Env == EnvProduction } 337 338func getDefault(key, def string) string { 339 if v := strings.TrimSpace(os.Getenv(key)); v != "" { 340 return v 341 } 342 return def 343} 344 345func getInt(key string, def int) int { 346 if v := strings.TrimSpace(os.Getenv(key)); v != "" { 347 if n, err := strconv.Atoi(v); err == nil { 348 return n 349 } 350 } 351 return def 352} 353 354func getBool(key string, def bool) bool { 355 if v := strings.TrimSpace(os.Getenv(key)); v != "" { 356 if b, err := strconv.ParseBool(v); err == nil { 357 return b 358 } 359 } 360 return def 361} 362 363// splitCSV splits a comma separated env value into trimmed, non empty entries. 364func splitCSV(v string) []string { 365 if strings.TrimSpace(v) == "" { 366 return nil 367 } 368 parts := strings.Split(v, ",") 369 out := make([]string, 0, len(parts)) 370 for _, p := range parts { 371 if t := strings.TrimSpace(p); t != "" { 372 out = append(out, t) 373 } 374 } 375 return out 376} 377 378// getBytes loads a secret key from the environment using an EXPLICIT encoding prefix so the key 379// material is never ambiguous: "base64:", "hex:", or "raw:". A bare value (no prefix) is decoded as 380// standard base64, and a decode failure is a hard error rather than a silent fall back to the raw 381// string. The silent fall back was a real footgun: a passphrase that happens to be valid base64 would 382// be decoded to different bytes than the operator intended, so the same variable could mean two 383// different keys in two contexts (a TOTP KEK that no longer decrypts its secrets, a pepper that no 384// longer verifies its passwords). Forcing the operator to declare the encoding removes that class of 385// bug. An unset variable yields nil with no error. 386func getBytes(key string) ([]byte, error) { 387 v := strings.TrimSpace(os.Getenv(key)) 388 if v == "" { 389 return nil, nil 390 } 391 switch { 392 case strings.HasPrefix(v, "raw:"): 393 return []byte(strings.TrimPrefix(v, "raw:")), nil 394 case strings.HasPrefix(v, "hex:"): 395 b, err := hex.DecodeString(strings.TrimPrefix(v, "hex:")) 396 if err != nil { 397 return nil, fmt.Errorf("%s: invalid hex value: %w", key, err) 398 } 399 return b, nil 400 case strings.HasPrefix(v, "base64:"): 401 b, err := base64.StdEncoding.DecodeString(strings.TrimPrefix(v, "base64:")) 402 if err != nil { 403 return nil, fmt.Errorf("%s: invalid base64 value: %w", key, err) 404 } 405 return b, nil 406 default: 407 b, err := base64.StdEncoding.DecodeString(v) 408 if err != nil { 409 return nil, fmt.Errorf("%s: value must be base64, or carry a raw: / hex: / base64: prefix: %w", key, err) 410 } 411 return b, nil 412 } 413} 414