Oakrey.Applications.SecureSettings 7.0.0

Oakrey.Applications.SecureSettings

Readable JSON settings support for critical application settings. It adds integrity protection, Windows-user authorization, and an audit history while keeping standard ISettingsService<T> available for regular Settings.json data.

Main features

• Separate secure file - secured settings are stored in SecuredSettings.json; regular settings remain in Settings.json.
• Readable JSON - secured values remain visible to users, but unnoticed external edits are detected.
• External change detection - the whole secured settings payload and history are signed with HMACSHA256.
• Authorized changes only - writes are allowed only when ISecureSettingsChangeAuthorizer approves the current Windows user.
• Audit history - each persistent secured setting change stores the user, machine, application version, section, key, old value, and new value.
• Explicit API - critical settings use ISecuredSettingsService<T> or SecuredSettingsBase; normal settings continue to use ISettingsService<T> and SettingsBase.

Configuration

Register the standard and secured settings services side by side:

services
    .ConfigureSettingUnderlyingServices()
    .ConfigureSecureSettingService(options =>
    {
        options.AllowedUserNames.Add(@"DOMAIN\UserName");
        options.AllowedRoles.Add(@"BUILTIN\Administrators");
    });

ConfigureSettingUnderlyingServices() registers the regular ISettingsService<T> backed by Settings.json. ConfigureSecureSettingService() registers ISecuredSettingsService<T> backed by SecuredSettings.json and does not replace the regular service.

If no user or role is configured, any authenticated Windows user running the application is allowed to change secured settings.

Example usage

Regular settings can stay unchanged:

public sealed class UiSettings(ISettingsService<UiSettings> settingsService)
    : SettingsBase(settingsService)
{
    public string Theme
    {
        get => Get<string>() ?? "Dark";
        set => Set(value);
    }
}

Critical settings opt in to the secured service:

public sealed class CalibrationSettings(ISecuredSettingsService<CalibrationSettings> settingsService)
    : SecuredSettingsBase(settingsService)
{
    public double Gain
    {
        get => Get<double>();
        set => Set(value);
    }
}

File paths

By default, DefaultSecuredSettingsPathProvider stores SecuredSettings.json in the same directory as IApplicationInfo.UserSettingsPath. Applications with a different layout can replace ISecuredSettingsPathProvider.

JSON shape

The secured settings file stays readable:

{
  "Version": 1,
  "Settings": {
    "My.Application.CalibrationSettings": {
      "Gain": {
        "Type": "System.Double",
        "Value": 1.25
      }
    }
  },
  "History": [],
  "Protection": {
    "Algorithm": "HMACSHA256",
    "KeyId": "LocalUserProfile:...",
    "Signature": "...",
    "SignedAtUtc": "2026-07-09T08:00:00+00:00"
  }
}

Manual edits to Settings or History invalidate Protection.Signature; the next load throws SecureSettingsTamperException.

Integrity key

The default UserProfileSecureSettingsIntegrityKeyProvider creates a random key in the current user's local application data folder. Applications that need a different key lifecycle can replace ISecureSettingsIntegrityKeyProvider.

Security note

This project protects SecuredSettings.json from unnoticed external modification and enforces application-level authorization before writes. It does not make the JSON confidential; values are intentionally readable by users.