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 "time" 18) 19 20// Env is the deployment environment. 21type Env string 22 23const ( 24 EnvDevelopment Env = "development" 25 EnvProduction Env = "production" 26) 27 28// Cloud is the target government cloud. Local is for dev (MinIO, self-hosted embeddings, no managed services). 29type Cloud string 30 31const ( 32 CloudLocal Cloud = "local" 33 CloudAWSGovCloud Cloud = "aws_govcloud" 34 CloudAzureGov Cloud = "azure_gov" 35) 36 37// EmbeddingProvider selects the embedding adapter. "fake" is a deterministic offline provider for 38// dev/tests; "openai" is any OpenAI compatible endpoint (self hosted vLLM, the production CUI path, 39// or OpenAI); "bedrock"/"azure_openai" are the managed gov cloud adapters (wired at deploy time). 40type EmbeddingProvider string 41 42const ( 43 ProviderFake EmbeddingProvider = "fake" 44 ProviderOpenAI EmbeddingProvider = "openai" 45 ProviderBedrock EmbeddingProvider = "bedrock" 46 ProviderAzureOpenAI EmbeddingProvider = "azure_openai" 47 // ProviderMegamind routes embeddings through the stateless MEGAMIND inference plane (the typed 48 // inference client to the gateway), the production self hosted path for cleared CUI data. 49 ProviderMegamind EmbeddingProvider = "megamind" 50) 51 52// Embeddings configures the embedding provider. Dimension MUST match the vector(N) column width in 53// the schema (default 384); changing the provider's native dimension is a re-embed migration, not a 54// config flip (STACK_DECISIONS.md §6). 55type Embeddings struct { 56 Provider EmbeddingProvider 57 Endpoint string // base URL for the OpenAI-compatible / Azure endpoint 58 Model string // e.g. "text-embedding-3-large", "amazon.titan-embed-text-v2:0", a local model id 59 Dimension int 60 APIKey string // bearer/api-key; for Bedrock/Azure-Entra the adapter uses cloud credentials instead 61 MegamindURL string // base URL of the MEGAMIND gateway when Provider is "megamind" 62} 63 64// Inference configures the typed client to the stateless MEGAMIND inference plane (embeddings, 65// reranking, generation, faithfulness). The heavy models run out of process on the Apple Silicon 66// cluster; this is the only AI compute the FIPS API binary reaches, over HTTP. URL empty means the AI 67// layer is unconfigured and its routes degrade rather than fail the boot. 68type Inference struct { 69 URL string // MEGAMIND gateway base, reached over Tailscale 70 EmbedModel string // 384 dim embedder (all-minilm or bge-small-en-v1.5) 71 RerankModel string // cross encoder (bge-reranker-v2-m3) or the cosine baseline 72 GenerateModel string // local instruct model (e.g. llama3.1:8b) 73 Dimension int // must match the vector(N) column width 74 TimeoutSeconds int // per request 75 MaxRetries int // additional attempts on a transient failure 76 BreakerTrips int // consecutive failures before the breaker opens 77 BreakerCoolSec int // how long the breaker stays open 78 TeachingEnabled bool // federated craft signal transmission; disabled until multiple live clients exist 79} 80 81// ExtractorProvider selects the Mission Check structured extraction adapter (resume or job description 82// text to proposed fields). "deterministic" is the offline rules plus ontology extractor and the 83// default; an LLM backed provider (self hosted vLLM for CUI in production) is a future addition behind 84// the same port. Extraction runs server side only, so a key here never reaches the browser bundle. 85type ExtractorProvider string 86 87const ( 88 ExtractorDeterministic ExtractorProvider = "deterministic" 89) 90 91// Extraction configures the Mission Check structured extraction provider. Endpoint, Model, and APIKey 92// are reserved for a future provider backed extractor and are unused by the deterministic one. 93type Extraction struct { 94 Provider ExtractorProvider 95 Endpoint string 96 Model string 97 APIKey string 98} 99 100// Auth holds the server side secrets and tunables for the authentication module. Every secret here 101// loads from the environment (the root owned secrets file), never the repo or the browser bundle. 102type Auth struct { 103 PepperVersion int // active credential pepper version stored on new credentials 104 Pepper []byte // active credential pepper key (HMAC applied before PBKDF2) 105 PepperPrevious []byte // optional prior pepper key (version PepperVersion minus 1) for rotation 106 TOTPKEKVersion int // active TOTP secret KEK version 107 TOTPKEK []byte // 32 byte AES 256 key encrypting TOTP secrets at rest 108 TOTPKEKPrevious []byte // optional prior TOTP KEK (version TOTPKEKVersion minus 1) so a rotated KEK still decrypts older secrets 109 // OrgSecretKEK seals per organization credentials in org_secrets: a customer's own SMTP password today, 110 // a source connector credential when in place federation lands. It is a SEPARATE key from the TOTP KEK 111 // on purpose. Both are 32 byte AES 256 keys handled by the same primitive, but they protect different 112 // populations of secret with different rotation pressure, and one key covering both means one disclosure 113 // covers both. When it is unset, storing an organization secret fails closed and says so. 114 OrgSecretKEKVersion int 115 OrgSecretKEK []byte 116 OrgSecretKEKPrevious []byte 117 CSRFKey []byte // HMAC key binding a CSRF token to its session 118 RecoveryLookupKey []byte // HMAC key for recovery code lookup tags 119 TOTPIssuer string // issuer shown in the authenticator app 120 SessionIdleSeconds int // idle timeout (NIST 800-171 3.1.11 default 900) 121 SessionAbsoluteSeconds int // absolute session cap (default 43200, 12 hours) 122 PendingAbsoluteSeconds int // auth_pending (pre MFA) session cap (default 300) 123 InviteExpirySeconds int // invite and activation link lifetime (default 259200, 72 hours) 124 CookieSecure bool // Secure attribute on the session cookie (true except plain http dev) 125 MFARequired bool // when false, login mints an active session after password with no TOTP step (pilot only, forbidden in production) 126 // OperatorMFARequired governs the operator seat alone. Amendment 6 decision 1 makes a second factor 127 // mandatory for operator from the day the role exists, independent of MM_MFA_REQUIRED, and that stays 128 // the DEFAULT here so the rule holds unless a deployment deliberately stands it down. 129 // 130 // It is a setting rather than a constant because Joseph explicitly directed, on 28 July 2026, that his 131 // production operator account not be prompted for MFA at this time. Making that a configuration value 132 // keeps his decision in one auditable place instead of deleting the rule from the code, keeps the 133 // staging gate proving the rule on its default, and turns re arming it into an env change rather than a 134 // release. Like MM_MFA_REQUIRED it cannot be stood down in a production MM_ENV. 135 OperatorMFARequired bool 136} 137 138// Config is the fully-resolved, validated application configuration. 139type Config struct { 140 Env Env 141 HTTPAddr string 142 // AppDBRole is the database role the app pool MUST authenticate as, asserted at boot. It is 143 // configuration rather than a constant so an environment can run under its OWN isolated role: staging 144 // and production share one Postgres cluster, so staging running as the production app role means the 145 // staging process can reach the production database. Naming the expected role per environment is what 146 // lets staging hold a role with zero privileges on production while the assertion stays exactly as 147 // strict, still failing the boot closed on a mismatch and still refusing a role with BYPASSRLS. 148 AppDBRole string 149 AppDatabaseURL string // NOBYPASSRLS app role DSN 150 MigratorDatabaseURL string // BYPASSRLS migrator role DSN (used by goose only) 151 ComplianceDatabaseURL string // compliance role DSN, the only path that reads the eeo schema; empty disables adverse impact reporting (503) 152 AioeDatabaseURL string // the dedicated missionmatch_aioe role DSN for the optimization engine batch updater; empty leaves the updater off while outcome capture keeps recording 153 AioeShadowMode bool // when true the updater proposes candidate weight profiles a human must promote, never auto activating (the safe pilot posture) 154 SecretsFile string // path of the root owned KEY=VALUE secret file (0600); empty means env only (local dev) 155 DecisionRetentionDays int // retention window for identifiable screening artifacts after a decision (default 90) 156 Cloud Cloud 157 Embeddings Embeddings 158 Inference Inference 159 Extraction Extraction 160 RequireFIPS bool // when true, cmd/api aborts unless crypto/fips140.Enabled() 161 AllowDevHeaderAuth bool // dev only X-Org-ID resolver toggle; MUST be false in production 162 // AllowSelfHostedProduction lets a production deployment run with MM_CLOUD=local. It exists so a self 163 // hosted federation can enforce every OTHER production control without lying about which cloud it is on. 164 AllowSelfHostedProduction bool 165 CurationEnforceSeparation bool // MM_CURATION_SEPARATION_OF_DUTIES: require the curation verifier to differ from the approver (default true); a single operator pilot may set it false to self verify, an explicit audited choice 166 BidOutcomesEnabled bool // MM_BID_OUTCOMES_ENABLED: gate the M7 bid outcomes recording routes (default false); ships DORMANT so the ledger accrues win and loss labels only once an operator turns it on, no learned model consumes it yet 167 AllowedOrigins []string // CSRF Origin allowlist for unsafe verbs; empty disables the check (dev) 168 TrustedProxyHeader string // header carrying the real client IP (set by a trusted reverse proxy); empty uses the TCP peer 169 // AppBaseURL is the public address of the web application, used to build the activation link inside an 170 // invitation email. It DEFAULTS to the first allowed origin rather than to a guess, because that value is 171 // already the address the browser really talks to, and a credential bearing link to the wrong hostname is 172 // worse than no link at all. 173 AppBaseURL string 174 Auth Auth 175 Federated Federated 176 Tenancy Tenancy 177} 178 179// TenancyMode selects how tenant isolation is achieved physically. 180type TenancyMode string 181 182const ( 183 // TenancyShared is the pool model: one database, every tenant's rows in the same tables, isolation 184 // enforced by forced Row Level Security and the per request org GUC. This is the default and the 185 // posture the product has shipped with. 186 TenancyShared TenancyMode = "shared" 187 188 // TenancyPerTenant is the silo model: each organization's business data lives in its OWN database, 189 // resolved per request through the tenant directory. RLS stays forced inside every tenant database, 190 // so the two mechanisms stack rather than one replacing the other. 191 // 192 // The reason this mode exists is not only isolation. Because the directory records a host and port 193 // per tenant, tenants can live on DIFFERENT MACHINES, which is what lets the deployment spread load 194 // across the federation without ever needing multi master writes: every tenant still has exactly one 195 // primary, so the row locks that enforce seat caps, stage transitions, and ownership claims keep 196 // working unchanged. 197 TenancyPerTenant TenancyMode = "per_tenant" 198) 199 200// Tenancy configures the database per tenant routing layer. It is INERT in shared mode: none of the 201// pool, directory, or secret resolver machinery is constructed unless Mode is per_tenant. 202type Tenancy struct { 203 Mode TenancyMode 204 205 // SecretsBackend resolves a tenant's credential REFERENCE from the directory into a real DSN. 206 // "env" reads a root owned environment file (development and staging); the government cloud stores 207 // are wired at deploy so no cloud SDK enters the core build. 208 SecretsBackend string 209 210 // SecretTTL bounds how long a resolved tenant DSN is cached before the backend is consulted again. 211 // A rotated credential is additionally picked up immediately on an authentication failure, because 212 // the pool manager forgets the reference and retries once. 213 SecretTTL time.Duration 214 215 // MaxPools caps how many tenant pools are live at once, least recently used evicted beyond it. The 216 // product of MaxPools and MaxConnsPerPool must stay under the server's max_connections, which is why 217 // both are configuration rather than constants. 218 MaxPools int 219 220 // MaxConnsPerPool keeps each tenant pool small, since many exist concurrently. 221 MaxConnsPerPool int 222 223 // IdleEvict closes a whole tenant pool after this long with no use, freeing the pool object itself 224 // rather than merely shrinking it the way pgx per connection idle close does. 225 IdleEvict time.Duration 226} 227 228// Federated configures the cross tenant differential privacy aggregation path (WS8). It is INERT by 229// default: the whole federated package is dead code unless Enabled is true and a real cohort of five or 230// more live non test tenants exists. Epsilon and Delta are the privacy budget, expressed as 231// configuration and never as code constants so a privacy officer can sign off and tune them without a 232// rebuild. In tenant LIVE keeps this off, only the in tenant producer and the human approved curation 233// pipeline ship enabled. 234type Federated struct { 235 DPEnabled bool // MM_FEDERATED_DP_ENABLED: master switch for the cross tenant DP release path (default false) 236 DPEpsilon float64 // MM_FEDERATED_DP_EPSILON: the (epsilon, delta) DP budget epsilon target (default 10) 237 DPDelta float64 // MM_FEDERATED_DP_DELTA: the (epsilon, delta) DP budget delta target (default 1e-7) 238} 239 240// Load reads configuration from the environment, applies defaults, and validates it. 241func Load() (Config, error) { 242 // Secret key decode errors are collected and surfaced alongside validation errors, so a 243 // misconfigured deploy sees every problem at once instead of one boot failure at a time. 244 var secretErrs []error 245 getB := func(key string) []byte { 246 b, err := getBytes(key) 247 if err != nil { 248 secretErrs = append(secretErrs, err) 249 } 250 return b 251 } 252 c := Config{ 253 Env: Env(getDefault("MM_ENV", string(EnvDevelopment))), 254 HTTPAddr: getDefault("MM_HTTP_ADDR", ":8080"), 255 AppDBRole: getDefault("MM_APP_DB_ROLE", "missionmatch_app"), 256 AppDatabaseURL: os.Getenv("MM_DATABASE_URL"), 257 MigratorDatabaseURL: os.Getenv("MM_MIGRATOR_DATABASE_URL"), 258 ComplianceDatabaseURL: os.Getenv("MM_COMPLIANCE_DATABASE_URL"), 259 AioeDatabaseURL: os.Getenv("MM_AIOE_DATABASE_URL"), 260 AioeShadowMode: os.Getenv("MM_AIOE_SHADOW") == "true", 261 SecretsFile: os.Getenv("MM_SECRETS_FILE"), 262 DecisionRetentionDays: getInt("MM_DECISION_RETENTION_DAYS", 90), 263 Tenancy: Tenancy{ 264 // Shared is the default, so an existing deployment that sets none of these keeps its current 265 // behaviour exactly. Per tenant routing is opt in, per environment. 266 Mode: TenancyMode(getDefault("MM_TENANCY_MODE", string(TenancyShared))), 267 SecretsBackend: getDefault("MM_TENANT_SECRETS_BACKEND", "env"), 268 SecretTTL: getDuration("MM_TENANT_SECRET_TTL", 15*time.Minute), 269 MaxPools: getInt("MM_TENANT_MAX_POOLS", 32), 270 MaxConnsPerPool: getInt("MM_TENANT_MAX_CONNS_PER_POOL", 4), 271 IdleEvict: getDuration("MM_TENANT_IDLE_EVICT", 15*time.Minute), 272 }, 273 Cloud: Cloud(getDefault("MM_CLOUD", string(CloudLocal))), 274 Embeddings: Embeddings{ 275 Provider: EmbeddingProvider(getDefault("MM_EMBED_PROVIDER", string(ProviderFake))), 276 Endpoint: os.Getenv("MM_EMBED_ENDPOINT"), 277 Model: os.Getenv("MM_EMBED_MODEL"), 278 Dimension: getInt("MM_EMBED_DIMENSION", 384), 279 APIKey: os.Getenv("MM_EMBED_API_KEY"), 280 MegamindURL: os.Getenv("MM_MEGAMIND_URL"), 281 }, 282 Inference: Inference{ 283 URL: os.Getenv("MM_MEGAMIND_URL"), 284 // bge-small-en-v1.5 (384 dim) is the production embedder, served on Ollama as the qllama handle. 285 // Stored and query vectors MUST use the same model: switching the model requires a FULL re 286 // backfill (existing vectors from another model are incompatible), see DEPLOY_PLAN.md. 287 EmbedModel: getDefault("MM_MEGAMIND_EMBED_MODEL", "qllama/bge-small-en-v1.5"), 288 RerankModel: getDefault("MM_MEGAMIND_RERANK_MODEL", "bge-reranker-v2-m3"), 289 GenerateModel: getDefault("MM_MEGAMIND_GENERATE_MODEL", "llama3.1:8b"), 290 Dimension: getInt("MM_EMBED_DIMENSION", 384), 291 TimeoutSeconds: getInt("MM_MEGAMIND_TIMEOUT_SECONDS", 30), 292 MaxRetries: getInt("MM_MEGAMIND_MAX_RETRIES", 2), 293 BreakerTrips: getInt("MM_MEGAMIND_BREAKER_TRIPS", 5), 294 BreakerCoolSec: getInt("MM_MEGAMIND_BREAKER_COOL_SECONDS", 30), 295 TeachingEnabled: getBool("MM_MEGAMIND_TEACHING_ENABLED", false), 296 }, 297 Extraction: Extraction{ 298 Provider: ExtractorProvider(getDefault("MM_EXTRACT_PROVIDER", string(ExtractorDeterministic))), 299 Endpoint: os.Getenv("MM_EXTRACT_ENDPOINT"), 300 Model: os.Getenv("MM_EXTRACT_MODEL"), 301 APIKey: os.Getenv("MM_EXTRACT_API_KEY"), 302 }, 303 RequireFIPS: getBool("MM_REQUIRE_FIPS", false), 304 AllowDevHeaderAuth: getBool("MM_ALLOW_DEV_HEADER_AUTH", false), 305 AllowSelfHostedProduction: getBool("MM_ALLOW_SELF_HOSTED_PRODUCTION", false), 306 CurationEnforceSeparation: getBool("MM_CURATION_SEPARATION_OF_DUTIES", true), 307 BidOutcomesEnabled: getBool("MM_BID_OUTCOMES_ENABLED", false), 308 AllowedOrigins: splitCSV(os.Getenv("MM_ALLOWED_ORIGINS")), 309 TrustedProxyHeader: os.Getenv("MM_TRUSTED_PROXY_HEADER"), 310 AppBaseURL: strings.TrimRight(strings.TrimSpace(os.Getenv("MM_APP_BASE_URL")), "/"), 311 Auth: Auth{ 312 PepperVersion: getInt("MM_CREDENTIAL_PEPPER_VERSION", 1), 313 Pepper: getB("MM_CREDENTIAL_PEPPER"), 314 PepperPrevious: getB("MM_CREDENTIAL_PEPPER_PREVIOUS"), 315 TOTPKEKVersion: getInt("MM_TOTP_KEK_VERSION", 1), 316 TOTPKEK: getB("MM_TOTP_KEK"), 317 TOTPKEKPrevious: getB("MM_TOTP_KEK_PREVIOUS"), 318 OrgSecretKEKVersion: getInt("MM_ORG_SECRET_KEK_VERSION", 1), 319 OrgSecretKEK: getB("MM_ORG_SECRET_KEK"), 320 OrgSecretKEKPrevious: getB("MM_ORG_SECRET_KEK_PREVIOUS"), 321 CSRFKey: getB("MM_CSRF_KEY"), 322 RecoveryLookupKey: getB("MM_RECOVERY_LOOKUP_KEY"), 323 TOTPIssuer: getDefault("MM_TOTP_ISSUER", "missionMATCH"), 324 SessionIdleSeconds: getInt("MM_SESSION_IDLE_SECONDS", 900), 325 SessionAbsoluteSeconds: getInt("MM_SESSION_ABSOLUTE_SECONDS", 43200), 326 PendingAbsoluteSeconds: getInt("MM_SESSION_PENDING_SECONDS", 300), 327 InviteExpirySeconds: getInt("MM_INVITE_EXPIRY_SECONDS", 259200), 328 CookieSecure: getBool("MM_COOKIE_SECURE", true), 329 MFARequired: getBool("MM_MFA_REQUIRED", true), 330 OperatorMFARequired: getBool("MM_OPERATOR_MFA_REQUIRED", true), 331 }, 332 Federated: Federated{ 333 DPEnabled: getBool("MM_FEDERATED_DP_ENABLED", false), 334 DPEpsilon: getFloat("MM_FEDERATED_DP_EPSILON", 10), 335 DPDelta: getFloat("MM_FEDERATED_DP_DELTA", 1e-7), 336 }, 337 } 338 if err := c.Validate(); err != nil { 339 secretErrs = append(secretErrs, err) 340 } 341 if len(secretErrs) > 0 { 342 return Config{}, errors.Join(secretErrs...) 343 } 344 return c, nil 345} 346 347// Validate enforces invariants and environment-specific requirements. Errors are joined so a 348// misconfigured deploy surfaces every problem at once. 349func (c Config) Validate() error { 350 var errs []error 351 352 switch c.Env { 353 case EnvDevelopment, EnvProduction: 354 default: 355 errs = append(errs, fmt.Errorf("MM_ENV %q invalid (want development|production)", c.Env)) 356 } 357 switch c.Cloud { 358 case CloudLocal, CloudAWSGovCloud, CloudAzureGov: 359 default: 360 errs = append(errs, fmt.Errorf("MM_CLOUD %q invalid (want local|aws_govcloud|azure_gov)", c.Cloud)) 361 } 362 // The activation link host falls back to the first allowed origin, which is already the exact address the 363 // browser is permitted to talk to. Deriving it means one fewer setting an operator can get wrong, and the 364 // derived value cannot point somewhere the CSRF allowlist would have refused anyway. 365 if c.AppBaseURL == "" && len(c.AllowedOrigins) > 0 { 366 c.AppBaseURL = strings.TrimRight(strings.TrimSpace(c.AllowedOrigins[0]), "/") 367 } 368 switch c.Embeddings.Provider { 369 case ProviderFake, ProviderOpenAI, ProviderBedrock, ProviderAzureOpenAI, ProviderMegamind: 370 default: 371 errs = append(errs, fmt.Errorf("MM_EMBED_PROVIDER %q invalid", c.Embeddings.Provider)) 372 } 373 if c.Embeddings.Dimension <= 0 { 374 errs = append(errs, errors.New("MM_EMBED_DIMENSION must be > 0")) 375 } 376 377 switch c.Tenancy.Mode { 378 // Empty is shared. A Config built programmatically rather than through Load leaves Tenancy zero 379 // valued, and the zero value must mean the default posture rather than a validation failure. 380 case TenancyShared, "": 381 case TenancyPerTenant: 382 // In per tenant mode MM_DATABASE_URL stops being the data plane and becomes the CONTROL PLANE 383 // pool: it is what the router reads the tenant directory through. Without it there is no way to 384 // discover any tenant database, so the service could not serve a single request. 385 if c.AppDatabaseURL == "" { 386 errs = append(errs, errors.New("MM_DATABASE_URL (the control plane pool) required when MM_TENANCY_MODE=per_tenant")) 387 } 388 if c.Tenancy.MaxPools < 1 { 389 errs = append(errs, errors.New("MM_TENANT_MAX_POOLS must be >= 1")) 390 } 391 if c.Tenancy.MaxConnsPerPool < 1 { 392 errs = append(errs, errors.New("MM_TENANT_MAX_CONNS_PER_POOL must be >= 1")) 393 } 394 switch c.Tenancy.SecretsBackend { 395 case "env", "aws_govcloud", "azure_gov": 396 default: 397 errs = append(errs, fmt.Errorf("MM_TENANT_SECRETS_BACKEND %q invalid (want env|aws_govcloud|azure_gov)", c.Tenancy.SecretsBackend)) 398 } 399 default: 400 errs = append(errs, fmt.Errorf("MM_TENANCY_MODE %q invalid (want shared|per_tenant)", c.Tenancy.Mode)) 401 } 402 // Empty selects the deterministic extractor (the same default extraction.New applies), so a Config 403 // built without an explicit provider validates. 404 switch c.Extraction.Provider { 405 case ExtractorDeterministic, "": 406 default: 407 errs = append(errs, fmt.Errorf("MM_EXTRACT_PROVIDER %q invalid (want deterministic)", c.Extraction.Provider)) 408 } 409 410 // OpenAI-compatible providers need an endpoint + model. 411 if c.Embeddings.Provider == ProviderOpenAI || c.Embeddings.Provider == ProviderAzureOpenAI { 412 if c.Embeddings.Endpoint == "" { 413 errs = append(errs, fmt.Errorf("MM_EMBED_ENDPOINT required for provider %q", c.Embeddings.Provider)) 414 } 415 if c.Embeddings.Model == "" { 416 errs = append(errs, fmt.Errorf("MM_EMBED_MODEL required for provider %q", c.Embeddings.Provider)) 417 } 418 } 419 // The MEGAMIND provider needs the gateway URL and the embed model name. 420 if c.Embeddings.Provider == ProviderMegamind { 421 if c.Embeddings.MegamindURL == "" { 422 errs = append(errs, errors.New("MM_MEGAMIND_URL required for provider \"megamind\"")) 423 } 424 if c.Embeddings.Model == "" && c.Inference.EmbedModel == "" { 425 errs = append(errs, errors.New("MM_EMBED_MODEL or MM_MEGAMIND_EMBED_MODEL required for provider \"megamind\"")) 426 } 427 } 428 429 // TOTP secrets are AES 256, so the KEK must be exactly 32 bytes whenever it is set, in any env. 430 if len(c.Auth.TOTPKEK) != 0 && len(c.Auth.TOTPKEK) != 32 { 431 errs = append(errs, errors.New("MM_TOTP_KEK must decode to exactly 32 bytes (AES 256)")) 432 } 433 if len(c.Auth.TOTPKEKPrevious) != 0 && len(c.Auth.TOTPKEKPrevious) != 32 { 434 errs = append(errs, errors.New("MM_TOTP_KEK_PREVIOUS must decode to exactly 32 bytes (AES 256)")) 435 } 436 // Same rule for the organization secret KEK, and for the same reason: a key of the wrong length is a boot 437 // time mistake, not a runtime surprise discovered the first time a customer saves a password. 438 if len(c.Auth.OrgSecretKEK) != 0 && len(c.Auth.OrgSecretKEK) != 32 { 439 errs = append(errs, errors.New("MM_ORG_SECRET_KEK must decode to exactly 32 bytes (AES 256)")) 440 } 441 if len(c.Auth.OrgSecretKEKPrevious) != 0 && len(c.Auth.OrgSecretKEKPrevious) != 32 { 442 errs = append(errs, errors.New("MM_ORG_SECRET_KEK_PREVIOUS must decode to exactly 32 bytes (AES 256)")) 443 } 444 if c.Auth.PepperVersion <= 0 { 445 errs = append(errs, errors.New("MM_CREDENTIAL_PEPPER_VERSION must be positive")) 446 } 447 if c.Auth.SessionIdleSeconds <= 0 || c.Auth.SessionAbsoluteSeconds <= 0 || c.Auth.PendingAbsoluteSeconds <= 0 { 448 errs = append(errs, errors.New("session timeout seconds must all be positive")) 449 } 450 if c.DecisionRetentionDays <= 0 { 451 errs = append(errs, errors.New("MM_DECISION_RETENTION_DAYS must be positive")) 452 } 453 454 if c.Env == EnvProduction { 455 if c.AppDatabaseURL == "" { 456 errs = append(errs, errors.New("MM_DATABASE_URL required in production")) 457 } 458 if c.Embeddings.Provider == ProviderFake { 459 errs = append(errs, errors.New("the fake embedding provider must not be used in production")) 460 } 461 // A production deployment must name a government cloud, UNLESS the operator explicitly declares a 462 // self hosted deployment with MM_ALLOW_SELF_HOSTED_PRODUCTION. 463 // 464 // The check exists to stop someone shipping to a commercial region by accident, not to forbid 465 // running the platform on hardware you own. Self hosting is a legitimate posture for cleared work, 466 // and it is arguably the stricter one: nothing leaves the operator's own network. What is NOT 467 // acceptable is resolving the conflict by setting MM_CLOUD to a government cloud you are not on, 468 // because that string travels into compliance conversations and would be a false claim. 469 // 470 // So the escape hatch is deliberately a SEPARATE, explicitly named flag rather than a widening of 471 // the cloud vocabulary: MM_CLOUD keeps telling the truth (local), and the operator has to state 472 // once, on purpose, that local is intended here. It is logged at boot so it can never be a silent 473 // default that somebody inherits without knowing. 474 if c.Cloud == CloudLocal && !c.AllowSelfHostedProduction { 475 errs = append(errs, errors.New( 476 "MM_CLOUD must be a government cloud in production, or set MM_ALLOW_SELF_HOSTED_PRODUCTION=true "+ 477 "to declare a deliberate self hosted deployment")) 478 } 479 // The dev X-Org-ID resolver may never be the production tenant source. 480 if c.AllowDevHeaderAuth { 481 errs = append(errs, errors.New("MM_ALLOW_DEV_HEADER_AUTH must be false in production")) 482 } 483 // FIPS must be enforced, not optional, so the validated crypto path is the one that runs. 484 if !c.RequireFIPS { 485 errs = append(errs, errors.New("MM_REQUIRE_FIPS must be true in production")) 486 } 487 // Every auth secret must be present so the validated crypto has its keys. 488 if len(c.Auth.Pepper) == 0 { 489 errs = append(errs, errors.New("MM_CREDENTIAL_PEPPER required in production")) 490 } 491 if len(c.Auth.TOTPKEK) != 32 { 492 errs = append(errs, errors.New("MM_TOTP_KEK (32 byte AES 256 key) required in production")) 493 } 494 if len(c.Auth.CSRFKey) == 0 { 495 errs = append(errs, errors.New("MM_CSRF_KEY required in production")) 496 } 497 if len(c.Auth.RecoveryLookupKey) == 0 { 498 errs = append(errs, errors.New("MM_RECOVERY_LOOKUP_KEY required in production")) 499 } 500 // The CSRF Origin allowlist must be enforced; an empty list disables it (a dev only path). 501 if len(c.AllowedOrigins) == 0 { 502 errs = append(errs, errors.New("MM_ALLOWED_ORIGINS required in production (the CSRF Origin allowlist must be enforced)")) 503 } 504 // Both cookies use the __Host- prefix, which a browser only accepts when Secure is set; a non 505 // Secure production deploy silently breaks all auth and exposes the token. 506 if !c.Auth.CookieSecure { 507 errs = append(errs, errors.New("MM_COOKIE_SECURE must be true in production (the __Host- cookie prefix requires Secure)")) 508 } 509 // MFA is mandatory in production. The pilot only password only relaxation can never ship to a 510 // government cloud, so a production deploy with it set is a hard configuration error. 511 if !c.Auth.MFARequired { 512 errs = append(errs, errors.New("MM_MFA_REQUIRED must be true in production (MFA is mandatory)")) 513 } 514 // The operator relaxation is a pilot accommodation like the one above, and it is refused in a 515 // production MM_ENV for the same reason: the platform plane reaches every tenant at once, so it is 516 // the last seat that should ever be reachable with a password alone in a government cloud. 517 if !c.Auth.OperatorMFARequired { 518 errs = append(errs, errors.New("MM_OPERATOR_MFA_REQUIRED must be true in production (the platform plane always requires a second factor)")) 519 } 520 } 521 522 return errors.Join(errs...) 523} 524 525// IsProduction reports whether this is a production deployment. 526func (c Config) IsProduction() bool { return c.Env == EnvProduction } 527 528func getDefault(key, def string) string { 529 if v := strings.TrimSpace(os.Getenv(key)); v != "" { 530 return v 531 } 532 return def 533} 534 535func getInt(key string, def int) int { 536 if v := strings.TrimSpace(os.Getenv(key)); v != "" { 537 if n, err := strconv.Atoi(v); err == nil { 538 return n 539 } 540 } 541 return def 542} 543 544// getDuration reads a Go duration string such as "15m" or "90s". An unparseable value falls back to the 545// default rather than failing the boot, matching how getInt and getBool already behave: a malformed 546// tuning knob should not take the service down, and the effective value is logged at startup. 547func getDuration(key string, def time.Duration) time.Duration { 548 if v := strings.TrimSpace(os.Getenv(key)); v != "" { 549 if d, err := time.ParseDuration(v); err == nil { 550 return d 551 } 552 } 553 return def 554} 555 556func getBool(key string, def bool) bool { 557 if v := strings.TrimSpace(os.Getenv(key)); v != "" { 558 if b, err := strconv.ParseBool(v); err == nil { 559 return b 560 } 561 } 562 return def 563} 564 565func getFloat(key string, def float64) float64 { 566 if v := strings.TrimSpace(os.Getenv(key)); v != "" { 567 if f, err := strconv.ParseFloat(v, 64); err == nil { 568 return f 569 } 570 } 571 return def 572} 573 574// splitCSV splits a comma separated env value into trimmed, non empty entries. 575func splitCSV(v string) []string { 576 if strings.TrimSpace(v) == "" { 577 return nil 578 } 579 parts := strings.Split(v, ",") 580 out := make([]string, 0, len(parts)) 581 for _, p := range parts { 582 if t := strings.TrimSpace(p); t != "" { 583 out = append(out, t) 584 } 585 } 586 return out 587} 588 589// getBytes loads a secret key from the environment using an EXPLICIT encoding prefix so the key 590// material is never ambiguous: "base64:", "hex:", or "raw:". A bare value (no prefix) is decoded as 591// standard base64, and a decode failure is a hard error rather than a silent fall back to the raw 592// string. The silent fall back was a real footgun: a passphrase that happens to be valid base64 would 593// be decoded to different bytes than the operator intended, so the same variable could mean two 594// different keys in two contexts (a TOTP KEK that no longer decrypts its secrets, a pepper that no 595// longer verifies its passwords). Forcing the operator to declare the encoding removes that class of 596// bug. An unset variable yields nil with no error. 597func getBytes(key string) ([]byte, error) { 598 v := strings.TrimSpace(os.Getenv(key)) 599 if v == "" { 600 return nil, nil 601 } 602 switch { 603 case strings.HasPrefix(v, "raw:"): 604 return []byte(strings.TrimPrefix(v, "raw:")), nil 605 case strings.HasPrefix(v, "hex:"): 606 b, err := hex.DecodeString(strings.TrimPrefix(v, "hex:")) 607 if err != nil { 608 return nil, fmt.Errorf("%s: invalid hex value: %w", key, err) 609 } 610 return b, nil 611 case strings.HasPrefix(v, "base64:"): 612 b, err := base64.StdEncoding.DecodeString(strings.TrimPrefix(v, "base64:")) 613 if err != nil { 614 return nil, fmt.Errorf("%s: invalid base64 value: %w", key, err) 615 } 616 return b, nil 617 default: 618 b, err := base64.StdEncoding.DecodeString(v) 619 if err != nil { 620 return nil, fmt.Errorf("%s: value must be base64, or carry a raw: / hex: / base64: prefix: %w", key, err) 621 } 622 return b, nil 623 } 624} 625