Skip to content

SAIF.Framework.Security.EnvironmentApi business rules

This page captures business rules enforced by this library.

BR-001: Configuration key must resolve or fail loudly

Field Value
Statement A configuration key not found in the developer override file, the in-memory cache, or the fetched section must fail loudly rather than silently return a default value.
Trigger GetConfigSettingInfo exhausts all lookup sources (override file, cache, and section fetch) for a requested key.
Enforcement Throws ApplicationException("The key '{0}' for track '{1}' and section '{2}' was not found").
Outcome Callers cannot silently receive a missing or default config value.
Source SAIF.Framework.Security.EnvironmentApi\Services.Common\EnvironmentServiceBase.cs

BR-002: Environment API base URL must be present

Field Value
Statement The Environment API base URL must be present as an OS environment variable before any environment-dependent operation executes.
Trigger Any access to EnvironmentApiUrl when Environment.GetEnvironmentVariable("EnvironmentApiUrl") is null.
Enforcement Throws MissingEnvironmentUrlVariableException.
Outcome Environment-dependent operations cannot proceed without a valid Environment API endpoint configured.
Source SAIF.Framework.Security.EnvironmentApi\Services.Common\EnvironmentServiceBase.cs, SAIF.Framework.Security.EnvironmentApi\Exceptions\MissingEnvironmentUrlVariableException.cs

BR-003: Configuration payload must declare a refresh interval

Field Value
Statement The environment configuration payload must declare a refresh-check interval.
Trigger A newly downloaded ConfigurationSettings.Settings dictionary lacking the checkforupdatedsettingsinseconds key.
Enforcement Throws KeyNotFoundException.
Outcome The refresh-throttling mechanism cannot silently operate with an undefined interval.
Source SAIF.Framework.Security.EnvironmentApi\Services.Common\EnvironmentServiceBase.cs

BR-004: Developer settings override requires developer-machine status

Field Value
Statement A developer-settings override file is only honored on a machine already classified as a developer machine.
Trigger Request for DeveloperSettingsFile when IsDeveloperMachine is false.
Enforcement The DeveloperSettingsFile getter only resolves the file path when IsDeveloperMachine is true; otherwise it falls back to an empty string.
Outcome Non-developer machines cannot use local configuration overrides to bypass the central Environment API.
Source SAIF.Framework.Security.EnvironmentApi\Services.Common\EnvironmentServiceBase.cs

BR-005: Developer-machine classification requires tag-number host and AD membership

Field Value
Statement A host is treated as a "developer machine" only if its name matches a tag-number pattern (^[TV]\d+$, case-insensitive) and it is a member of the developer_machine_users AD group.
Trigger IsDeveloperMachine property access.
Enforcement A regex check in IsMachineTagNumber short-circuits to false before the AD membership check via MachineSecurity.IsAuthorized.
Outcome Only hosts named with the tag-number convention and enrolled in the AD group are treated as developer machines; all other hosts skip the AD lookup entirely.
Source SAIF.Framework.Security.EnvironmentApi\Services.Common\EnvironmentServiceBase.cs

BR-006: Machine/service account authorization via AD group membership

Field Value
Statement A machine/service account is authorized against an AD "resource" group only if it is found — directly or via nested/recursive group membership — in that AD group, with account names compared case-insensitively after trimming $ suffixes.
Trigger MachineSecurityService.IsAuthorized call.
Enforcement String comparison loop in MachineSecurityService.IsAuthorized against members returned by ADService.GetUsersByGroup.
Outcome Machine accounts are authorized only when actual AD group membership (including nested groups) is confirmed.
Source SAIF.Framework.Security.EnvironmentApi\Core\Services\MachineSecurityService.cs

BR-007: Production vs. non-production AD resource-name convention

Field Value
Statement AD resource group names for production vs. non-production must be distinguished by suffix.
Trigger IsAuthorized(isResource: true, isProductionResource: false).
Enforcement groupName += "Test" then groupName += "Resource" in MachineSecurityService.IsAuthorized, matching the SAIF <ResourceName>Resource / <ResourceName>TestResource convention.
Outcome Production and non-production authorization checks are targeted at distinct AD groups, preventing accidental cross-environment authorization.
Source SAIF.Framework.Security.EnvironmentApi\Core\Services\MachineSecurityService.cs

BR-008: System hash must not be expired

Field Value
Statement A system hash used for secure config retrieval must not be older than its configured expiry window (allowing a caller-provided buffer).
Trigger RemoveSystemHashSaltAndValidateLifetime call.
Enforcement Throws SystemHashExpiredException when the un-salted creation timestamp falls outside the valid [now-buffer, expires) window.
Outcome Expired system hashes cannot be used to retrieve secure configuration settings.
Source SAIF.Framework.Security.EnvironmentApi\Services.Common\SystemHashUtil.cs

BR-009: Global section is the sole non-custom section

Field Value
Statement A "custom section" of configuration is any section other than the global section.*
Trigger ConfigKey.IsCustomSection/GetCustomSection/FormattedKey evaluation.
Enforcement Compares Section against Constants.GlobalSection ("global") case-insensitively.
Outcome Section-scoped configuration keys are distinguished from global keys for lookup and formatting purposes.
Source SAIF.Framework.Security.EnvironmentApi\Core\Contracts\Core\Configurations\ConfigurationSettings.cs

Notes

  • MachineSecurityService.IsAuthorized (enforcing BR-006 and BR-007) fails closed (returns false) on any AD-lookup exception, logging only via Debug.WriteLine* — see security-authorization.md for the full authorization architecture.

Note: Statements marked with * were inferred from code structure, naming conventions, or contextual evidence where direct confirmation was not available in source artifacts. Statements marked with ** could not be confirmed; treat as unknown until verified.

Sources

  • SAIF.Framework.Security.EnvironmentApi\Services.Common\EnvironmentServiceBase.cs
  • SAIF.Framework.Security.EnvironmentApi\Exceptions\MissingEnvironmentUrlVariableException.cs
  • SAIF.Framework.Security.EnvironmentApi\Core\Services\MachineSecurityService.cs
  • SAIF.Framework.Security.EnvironmentApi\Services.Common\SystemHashUtil.cs
  • SAIF.Framework.Security.EnvironmentApi\Core\Contracts\Core\Configurations\ConfigurationSettings.cs