AuthForgeClient.cs

using System;
using System.Collections.Generic;
using System.Diagnostics;
using System.Globalization;
using System.Linq;
using System.Net.Http;
using System.Net.NetworkInformation;
using System.Runtime.InteropServices;
using System.Security.Cryptography;
using System.Text;
using System.Text.Encodings.Web;
using System.Text.Json;
using System.Text.RegularExpressions;
using System.Threading;
using System.Threading.Tasks;
using Org.BouncyCastle.Crypto.Parameters;
using Org.BouncyCastle.Crypto.Signers;

namespace AuthForge
{
    /// <summary>
    /// Kind of session the client currently holds: an online server session
    /// (from <see cref="AuthForgeClient.Login"/>) or an offline license file
    /// (from <see cref="AuthForgeClient.LoginFromFile"/>).
    /// </summary>
    public enum SessionKind
    {
        Online,
        Offline,
    }

    public sealed partial class AuthForgeClient
    {
        private const string DefaultApiBaseUrl = "https://auth.authforge.cc";
        private static readonly JsonSerializerOptions CompactJsonOptions = new JsonSerializerOptions
        {
            Encoder = JavaScriptEncoder.UnsafeRelaxedJsonEscaping,
        };

        private readonly object _lock = new object();
        private readonly HttpClient _httpClient;
        private readonly HashSet<string> _knownServerErrors = new HashSet<string>(StringComparer.Ordinal)
        {
            "invalid_app",
            "invalid_key",
            "expired",
            "revoked",
            "hwid_mismatch",
            "no_credits",
            "app_burn_cap_reached",
            "blocked",
            "rate_limited",
            "replay_detected",
            "app_disabled",
            "session_expired",
            "revoke_requires_session",
            "bad_request",
            "malformed_request",
            "demo_quota_exceeded",
            "server_error",
            "system_error",
            "offline_activation_disabled",
            "offline_activation_requires_perpetual",
            "offline_activation_requires_seats",
            "offline_activation_limit_reached",
            "offline_file_rejected",
        };
        private static readonly Regex ServerErrorCodeRegex = new Regex("^[a-z][a-z0-9_]{0,63}$", RegexOptions.CultureInvariant);
        private static readonly string[] DefinitiveErrorCodeList =
        {
            "revoked",
            "expired",
            "hwid_mismatch",
            "blocked",
            "session_expired",
            "malformed_request",
            "app_disabled",
            "invalid_app",
            "signature_mismatch",
            "offline_activation_disabled",
            "offline_activation_requires_perpetual",
            "offline_activation_requires_seats",
            "offline_activation_limit_reached",
            "offline_file_rejected",
        };
        private static readonly HashSet<string> DefinitiveErrorCodeSet = new HashSet<string>(DefinitiveErrorCodeList, StringComparer.Ordinal);

        /// <summary>
        /// Codes that are an AuthForge verdict on the session or license. Every
        /// other code (network, timeout, <c>http_error_N</c>, <c>rate_limited</c>,
        /// <c>no_credits</c>, <c>unexpected_response</c>, unknown codes, ...) is transient.
        /// </summary>
        public static IReadOnlyCollection<string> DefinitiveErrorCodes { get; } = Array.AsReadOnly(DefinitiveErrorCodeList);

        /// <summary>True unless <paramref name="code"/> is in <see cref="DefinitiveErrorCodes"/>.</summary>
        public static bool IsTransientError(string? code)
        {
            return code is null || !DefinitiveErrorCodeSet.Contains(code);
        }

        private Thread? _heartbeatThread;
        private bool _heartbeatStarted;
        private ManualResetEventSlim? _heartbeatStopSignal;
        private int _sessionGeneration;

        private string? _licenseKey;
        private string? _sessionToken;
        private long? _sessionExpiresIn;
        private string? _lastNonce;
        private string? _rawPayloadB64;
        private string? _signature;
        private string? _keyId;
        private Dictionary<string, object?>? _sessionData;
        private Dictionary<string, object?>? _appVariables;
        private Dictionary<string, object?>? _licenseVariables;
        private bool _authenticated;
        private SessionKind? _sessionKind;
        private OfflineLicense? _offlineLicense;
        private readonly string _hwid;

        public string AppId { get; }
        /// <summary>
        /// Application secret. Required for online APIs
        /// (<see cref="Login"/>, <see cref="ValidateLicense"/>, <see cref="SelfBan"/>,
        /// <see cref="ActivateOffline"/>).
        /// May be empty for offline-only clients (<see cref="LoginFromFile"/>);
        /// air-gapped builds should not ship the secret.
        /// </summary>
        public string AppSecret { get; }
        public string PublicKey { get; }
        /// <summary>
        /// Full trust list of Ed25519 public keys. Always contains at least
        /// one entry; the first is the primary (current) key, additional
        /// entries are previous keys still trusted during a rotation window.
        /// </summary>
        public IReadOnlyList<string> PublicKeys { get; }
        /// <summary>
        /// When <c>true</c>, the SDK performs online check-ins: it calls
        /// <c>/auth/heartbeat</c> every <see cref="HeartbeatInterval"/> seconds
        /// for fast revocation and concurrent-use detection. When <c>false</c>
        /// (the default), the app runs through the grace period: it keeps
        /// re-verifying the signed session locally and fails once the session
        /// TTL expires, with no network traffic after activation.
        /// </summary>
        public bool OnlineHeartbeat { get; }
        /// <summary>
        /// Legacy mode string derived from <see cref="OnlineHeartbeat"/>:
        /// "SERVER" when online check-ins are enabled, otherwise "LOCAL".
        /// </summary>
        [Obsolete("HeartbeatMode is deprecated: use OnlineHeartbeat instead. \"SERVER\" corresponds to OnlineHeartbeat == true and \"LOCAL\" to the default (false).")]
        public string HeartbeatMode => OnlineHeartbeat ? "SERVER" : "LOCAL";
        public int HeartbeatInterval { get; }
        public string ApiBaseUrl { get; }
        public Action<string, Exception?>? OnFailure { get; }
        public int RequestTimeout { get; }
        /// <summary>
        /// Requested grace period duration (seconds), sent to /auth/validate as
        /// the session token lifetime. The grace period is how long the app
        /// keeps running on the signed session without contacting AuthForge.
        /// <c>null</c> (or &lt;= 0) means "let the server pick its default"
        /// (24h today). The server clamps to [3600, 604800] (1h to 7d);
        /// out-of-range values are silently clamped. Online check-ins refresh
        /// the token while preserving the requested lifetime.
        /// </summary>
        public int? TtlSeconds { get; }

        private readonly IReadOnlyList<Ed25519PublicKeyParameters> _verifyPublicKeys;

        /// <summary>
        /// Single-key constructor. Forwards to the rotation-aware overload
        /// with a single-entry trust list. Activates online via
        /// <c>/auth/validate</c>; by default the app then runs through the
        /// grace period (the session TTL) without contacting AuthForge. Set
        /// <paramref name="onlineHeartbeat"/> to <c>true</c> to enable online
        /// check-ins via <c>/auth/heartbeat</c>.
        /// </summary>
        public AuthForgeClient(
            string appId,
            string? appSecret,
            string publicKey,
            bool onlineHeartbeat = false,
            int heartbeatInterval = 900,
            string apiBaseUrl = DefaultApiBaseUrl,
            Action<string, Exception?>? onFailure = null,
            int requestTimeout = 15,
            int? ttlSeconds = null,
            string? hwidOverride = null)
            : this(
                appId,
                appSecret,
                NormalizePublicKeys(publicKey),
                onlineHeartbeat,
                heartbeatInterval,
                apiBaseUrl,
                onFailure,
                requestTimeout,
                ttlSeconds,
                hwidOverride)
        {
        }

        /// <summary>
        /// Legacy single-key constructor kept for source compatibility.
        /// Validates <paramref name="heartbeatMode"/> ("LOCAL" or "SERVER")
        /// and delegates to the <c>bool onlineHeartbeat</c> overload.
        /// </summary>
        [Obsolete("heartbeatMode is deprecated: LOCAL maps to the default grace period behavior (just remove the argument) and SERVER maps to onlineHeartbeat: true.")]
        public AuthForgeClient(
            string appId,
            string? appSecret,
            string publicKey,
            string heartbeatMode,
            int heartbeatInterval = 900,
            string apiBaseUrl = DefaultApiBaseUrl,
            Action<string, Exception?>? onFailure = null,
            int requestTimeout = 15,
            int? ttlSeconds = null,
            string? hwidOverride = null)
            : this(
                appId,
                appSecret,
                publicKey,
                ParseHeartbeatMode(heartbeatMode),
                heartbeatInterval,
                apiBaseUrl,
                onFailure,
                requestTimeout,
                ttlSeconds,
                hwidOverride)
        {
        }

        /// <summary>
        /// Legacy rotation-aware constructor kept for source compatibility.
        /// Validates <paramref name="heartbeatMode"/> ("LOCAL" or "SERVER")
        /// and delegates to the <c>bool onlineHeartbeat</c> overload.
        /// </summary>
        [Obsolete("heartbeatMode is deprecated: LOCAL maps to the default grace period behavior (just remove the argument) and SERVER maps to onlineHeartbeat: true.")]
        public AuthForgeClient(
            string appId,
            string? appSecret,
            IEnumerable<string> publicKeys,
            string heartbeatMode,
            int heartbeatInterval = 900,
            string apiBaseUrl = DefaultApiBaseUrl,
            Action<string, Exception?>? onFailure = null,
            int requestTimeout = 15,
            int? ttlSeconds = null,
            string? hwidOverride = null)
            : this(
                appId,
                appSecret,
                publicKeys,
                ParseHeartbeatMode(heartbeatMode),
                heartbeatInterval,
                apiBaseUrl,
                onFailure,
                requestTimeout,
                ttlSeconds,
                hwidOverride)
        {
        }

        /// <summary>
        /// Maps the legacy heartbeat mode string onto the onlineHeartbeat
        /// flag, preserving the historical validation error.
        /// </summary>
        private static bool ParseHeartbeatMode(string heartbeatMode)
        {
            var mode = (heartbeatMode ?? string.Empty).ToUpperInvariant();
            if (mode != "LOCAL" && mode != "SERVER")
            {
                throw new ArgumentException("heartbeat_mode must be LOCAL or SERVER", nameof(heartbeatMode));
            }
            return mode == "SERVER";
        }

        /// <summary>
        /// Primary rotation-aware constructor. Pass the current public key
        /// first, followed by any previous keys you want to remain trusted
        /// during a cutover. Verification accepts a signature that matches
        /// *any* key. Activates online via <c>/auth/validate</c>; by default
        /// the app then runs through the grace period (the session TTL)
        /// without contacting AuthForge. Set <paramref name="onlineHeartbeat"/>
        /// to <c>true</c> to enable online check-ins via <c>/auth/heartbeat</c>.
        /// <paramref name="appSecret"/> may be empty for offline-only clients
        /// (<see cref="LoginFromFile"/>); air-gapped builds should not ship it.
        /// </summary>
        public AuthForgeClient(
            string appId,
            string? appSecret,
            IEnumerable<string> publicKeys,
            bool onlineHeartbeat = false,
            int heartbeatInterval = 900,
            string apiBaseUrl = DefaultApiBaseUrl,
            Action<string, Exception?>? onFailure = null,
            int requestTimeout = 15,
            int? ttlSeconds = null,
            string? hwidOverride = null)
        {
            if (string.IsNullOrEmpty(appId))
            {
                throw new ArgumentException("app_id must be a non-empty string", nameof(appId));
            }

            // Empty/null is valid for offline-only clients (LoginFromFile).
            // Online APIs (Login, ValidateLicense, SelfBan) still require a secret.
            AppSecret = appSecret ?? string.Empty;
            var keyList = (publicKeys ?? Array.Empty<string>())
                .Where(k => !string.IsNullOrWhiteSpace(k))
                .Select(k => k.Trim())
                .Distinct(StringComparer.Ordinal)
                .ToList();
            if (keyList.Count == 0)
            {
                throw new ArgumentException(
                    "publicKeys must contain at least one non-empty base64 string",
                    nameof(publicKeys));
            }

            if (heartbeatInterval < 10)
            {
                throw new ArgumentException("heartbeat_interval must be >= 10", nameof(heartbeatInterval));
            }

            AppId = appId;
            PublicKeys = keyList;
            PublicKey = keyList[0];
            OnlineHeartbeat = onlineHeartbeat;
            HeartbeatInterval = heartbeatInterval;
            ApiBaseUrl = (apiBaseUrl ?? string.Empty).TrimEnd('/');
            OnFailure = onFailure;
            RequestTimeout = requestTimeout;
            TtlSeconds = ttlSeconds.HasValue && ttlSeconds.Value > 0 ? ttlSeconds : null;
            _httpClient = new HttpClient
            {
                Timeout = TimeSpan.FromSeconds(RequestTimeout),
            };
            var verifyKeys = new List<Ed25519PublicKeyParameters>(keyList.Count);
            foreach (var key in keyList)
            {
                byte[] publicKeyBytes;
                try
                {
                    publicKeyBytes = Convert.FromBase64String(key);
                }
                catch (FormatException ex)
                {
                    throw new ArgumentException("public_key must be valid base64", nameof(publicKeys), ex);
                }
                if (publicKeyBytes.Length != 32)
                {
                    throw new ArgumentException(
                        "public_key must be 32 bytes (base64 Ed25519 raw key)",
                        nameof(publicKeys));
                }
                verifyKeys.Add(new Ed25519PublicKeyParameters(publicKeyBytes, 0));
            }
            _verifyPublicKeys = verifyKeys;
            _hwid = ResolveHwid(hwidOverride);
        }

        /// <summary>
        /// Splits the historical single-string <c>publicKey</c> argument into
        /// the canonical list form. A comma separator is honoured so callers
        /// can plumb a trust list through environment variables.
        /// </summary>
        private static IEnumerable<string> NormalizePublicKeys(string publicKey)
        {
            if (string.IsNullOrWhiteSpace(publicKey))
            {
                return Array.Empty<string>();
            }
            return publicKey.Contains(',')
                ? publicKey.Split(',')
                : new[] { publicKey };
        }

        private void RequireAppSecret()
        {
            if (string.IsNullOrEmpty(AppSecret))
            {
                throw new ArgumentException(
                    "app_secret is required for online APIs; omit it only when using LoginFromFile",
                    nameof(AppSecret));
            }
        }

        public bool Login(string licenseKey)
        {
            if (string.IsNullOrEmpty(licenseKey))
            {
                throw new ArgumentException("license_key must be a non-empty string", nameof(licenseKey));
            }
            RequireAppSecret();

            try
            {
                ValidateAndStore(licenseKey);
                StartHeartbeatOnce();
                return true;
            }
            catch (Exception ex)
            {
                Fail("login_failed", ex);
                return false;
            }
        }

        /// <summary>
        /// Performs the same <c>/auth/validate</c> request and Ed25519 verification as <see cref="Login"/>,
        /// without updating client session state or starting the heartbeat thread.
        /// </summary>
        public ValidateLicenseResult ValidateLicense(string licenseKey)
        {
            if (string.IsNullOrEmpty(licenseKey))
            {
                throw new ArgumentException("license_key must be a non-empty string", nameof(licenseKey));
            }
            RequireAppSecret();

            try
            {
                var body = new Dictionary<string, object?>
                {
                    ["appId"] = AppId,
                    ["appSecret"] = AppSecret,
                    ["licenseKey"] = licenseKey,
                    ["hwid"] = _hwid,
                    ["nonce"] = GenerateNonce(),
                };
                if (TtlSeconds.HasValue)
                {
                    body["ttlSeconds"] = TtlSeconds.Value;
                }

                var responseObj = PostJson("/auth/validate", body);
                var expectedNonce = body.TryGetValue("nonce", out var usedNonce) ? (usedNonce?.ToString() ?? string.Empty) : string.Empty;
                var parsed = ParseSignedValidateResponse(responseObj, expectedNonce);
                var sessionData = ConvertToObjectMap(parsed.PayloadJson);
                var appVars = parsed.PayloadJson.TryGetValue("appVariables", out var appVarsElement)
                    ? ConvertJsonElementObject(appVarsElement)
                    : null;
                var licenseVars = parsed.PayloadJson.TryGetValue("licenseVariables", out var licenseVarsElement)
                    ? ConvertJsonElementObject(licenseVarsElement)
                    : null;
                return new ValidateLicenseResult
                {
                    Valid = true,
                    SessionToken = parsed.SessionToken,
                    ExpiresIn = parsed.ExpiresIn,
                    SessionData = new Dictionary<string, object?>(sessionData, StringComparer.Ordinal),
                    AppVariables = appVars is null ? null : new Dictionary<string, object?>(appVars, StringComparer.Ordinal),
                    LicenseVariables = licenseVars is null ? null : new Dictionary<string, object?>(licenseVars, StringComparer.Ordinal),
                    KeyId = parsed.KeyId,
                    SessionExpiresAt = parsed.SessionExpiresAt,
                    LicenseExpirationPresent = parsed.LicenseExpirationPresent,
                    LicenseExpiresAt = parsed.LicenseExpiresAt,
                    MaxHwidSlots = parsed.MaxHwidSlots,
                    HwidCount = parsed.HwidCount,
                    LicenseLabel = parsed.LicenseLabel,
                };
            }
            catch (Exception ex)
            {
                return new ValidateLicenseResult
                {
                    Valid = false,
                    ErrorCode = ex.Message,
                    Error = ex,
                };
            }
        }

        public Dictionary<string, object?> SelfBan(
            string? licenseKey = null,
            string? sessionToken = null,
            bool revokeLicense = true,
            bool blacklistHwid = true,
            bool blacklistIp = true)
        {
            string? currentSessionToken;
            string? currentLicenseKey;
            string hwid;
            SessionKind? currentKind;
            lock (_lock)
            {
                currentSessionToken = _sessionToken;
                currentLicenseKey = _licenseKey;
                hwid = _hwid;
                currentKind = _sessionKind;
            }

            // An offline session has no server session to revoke and no
            // license key the server should hear about: fail locally, no HTTP.
            if (currentKind == SessionKind.Offline
                && string.IsNullOrWhiteSpace(sessionToken)
                && string.IsNullOrWhiteSpace(licenseKey))
            {
                throw new ArgumentException("offline_session");
            }

            var resolvedSessionToken = string.IsNullOrWhiteSpace(sessionToken)
                ? currentSessionToken
                : sessionToken.Trim();
            if (!string.IsNullOrWhiteSpace(resolvedSessionToken))
            {
                var sessionBody = new Dictionary<string, object?>
                {
                    ["appId"] = AppId,
                    ["sessionToken"] = resolvedSessionToken,
                    ["hwid"] = hwid,
                    ["revokeLicense"] = revokeLicense,
                    ["blacklistHwid"] = blacklistHwid,
                    ["blacklistIp"] = blacklistIp,
                };
                var responseObj = PostJson("/auth/selfban", sessionBody);
                responseObj.TryGetValue("status", out var statusElement);
                if (!IsSuccessStatus(statusElement))
                {
                    throw new ArgumentException(ExtractServerError(responseObj));
                }
                return ConvertToObjectMap(responseObj);
            }

            var resolvedLicenseKey = string.IsNullOrWhiteSpace(licenseKey)
                ? currentLicenseKey
                : licenseKey.Trim();
            if (string.IsNullOrWhiteSpace(resolvedLicenseKey))
            {
                throw new ArgumentException("missing_license_key");
            }
            RequireAppSecret();

            var preSessionBody = new Dictionary<string, object?>
            {
                ["appId"] = AppId,
                ["appSecret"] = AppSecret,
                ["licenseKey"] = resolvedLicenseKey,
                ["hwid"] = hwid,
                ["nonce"] = GenerateNonce(),
                // Pre-session self-ban cannot revoke licenses.
                ["revokeLicense"] = false,
                ["blacklistHwid"] = blacklistHwid,
                ["blacklistIp"] = blacklistIp,
            };
            var preSessionResponse = PostJson("/auth/selfban", preSessionBody);
            preSessionResponse.TryGetValue("status", out var preSessionStatus);
            if (!IsSuccessStatus(preSessionStatus))
            {
                throw new ArgumentException(ExtractServerError(preSessionResponse));
            }
            return ConvertToObjectMap(preSessionResponse);
        }

        private void StartHeartbeatOnce()
        {
            lock (_lock)
            {
                if (_heartbeatStarted || _sessionKind == SessionKind.Offline)
                {
                    return;
                }

                var stopSignal = new ManualResetEventSlim(false);
                _heartbeatStopSignal = stopSignal;
                _heartbeatStarted = true;
                _heartbeatThread = new Thread(() => HeartbeatLoop(stopSignal))
                {
                    Name = "AuthForgeHeartbeat",
                    IsBackground = true,
                };
                _heartbeatThread.Start();
            }
        }

        private void HeartbeatLoop(ManualResetEventSlim stopSignal)
        {
            var interval = TimeSpan.FromSeconds(HeartbeatInterval);
            while (!stopSignal.Wait(interval))
            {
                if (!HeartbeatTick())
                {
                    break;
                }
            }
        }

        /// <summary>
        /// Runs one background check. Transient failures keep the session and
        /// return <c>true</c> so check-ins continue; without <see cref="OnFailure"/>
        /// they write a one-line warning to stderr. Definitive failures clear
        /// the session before <see cref="OnFailure"/> runs and return <c>false</c>.
        /// A result for a session that was replaced or logged out meanwhile is dropped.
        /// </summary>
        internal bool HeartbeatTick()
        {
            int generation;
            lock (_lock)
            {
                if (_sessionKind != SessionKind.Online)
                {
                    return false;
                }
                generation = _sessionGeneration;
            }

            AuthForgeException failure;
            try
            {
                if (OnlineHeartbeat)
                {
                    ServerHeartbeat(generation);
                }
                else
                {
                    GracePeriodCheck();
                }
                return true;
            }
            catch (Exception ex)
            {
                failure = NormalizeHeartbeatError(ex);
            }

            lock (_lock)
            {
                if (generation != _sessionGeneration)
                {
                    return _sessionKind == SessionKind.Online;
                }
                if (failure.IsTransient && LocalSessionExpiredLocked())
                {
                    failure = new AuthForgeException("session_expired", "session_expired", failure);
                }
                if (failure.IsFatal)
                {
                    ClearSessionLocked();
                }
            }

            if (failure.IsTransient && OnFailure is null)
            {
                WarnFn($"AuthForge: background check failed ({failure.Code}); retrying next interval");
                return true;
            }
            Fail("heartbeat_failed", failure);
            return failure.IsTransient;
        }

        internal static AuthForgeException NormalizeHeartbeatError(Exception ex)
        {
            if (ex is AuthForgeException authForgeException)
            {
                return authForgeException;
            }
            var message = ex.Message ?? string.Empty;
            if (ex.InnerException is TaskCanceledException)
            {
                return new AuthForgeException("timeout", message, ex);
            }
            var prefix = message.Split(':')[0].Trim().ToLowerInvariant();
            if (prefix == "url_error")
            {
                return new AuthForgeException("network_error", message, ex);
            }
            var code = ServerErrorCodeRegex.IsMatch(prefix) ? prefix : "unknown_error";
            return new AuthForgeException(code, message, ex);
        }

        private bool LocalSessionExpiredLocked()
        {
            return _sessionExpiresIn.HasValue
                && DateTimeOffset.UtcNow.ToUnixTimeSeconds() >= _sessionExpiresIn.Value;
        }

        private void ServerHeartbeat(int generation)
        {
            string? sessionToken;
            string hwid;
            lock (_lock)
            {
                sessionToken = _sessionToken;
                hwid = _hwid;
            }

            if (sessionToken is null || sessionToken.Length == 0)
            {
                throw new InvalidOperationException("missing_session_token");
            }

            var body = new Dictionary<string, object?>
            {
                ["appId"] = AppId,
                ["sessionToken"] = sessionToken,
                ["nonce"] = GenerateNonce(),
                ["hwid"] = hwid,
            };
            var responseObj = PostJson("/auth/heartbeat", body);
            responseObj.TryGetValue("status", out var statusElement);
            if (!IsSuccessStatus(statusElement))
            {
                throw HeartbeatRejection(responseObj);
            }
            var expectedNonce = body.TryGetValue("nonce", out var usedNonce) ? (usedNonce?.ToString() ?? string.Empty) : string.Empty;
            ApplySignedResponse(responseObj, expectedNonce, null, "heartbeat", generation);
        }

        /// <summary>
        /// A failed heartbeat body is an AuthForge verdict only when it is
        /// <c>{"status":"failed","error":"&lt;code&gt;"}</c>; anything else is
        /// <c>unexpected_response</c> (transient).
        /// </summary>
        private AuthForgeException HeartbeatRejection(Dictionary<string, JsonElement> responseObj)
        {
            responseObj.TryGetValue("status", out var statusElement);
            responseObj.TryGetValue("error", out var errorElement);
            var wellFormed = statusElement.ValueKind == JsonValueKind.String
                && string.Equals((statusElement.GetString() ?? string.Empty).Trim(), "failed", StringComparison.OrdinalIgnoreCase)
                && errorElement.ValueKind == JsonValueKind.String
                && (errorElement.GetString() ?? string.Empty).Trim().Length > 0;
            if (wellFormed)
            {
                return new AuthForgeException(ExtractServerError(responseObj));
            }
            return new AuthForgeException(
                "unexpected_response",
                $"unexpected_response: status={DescribeJson(statusElement)}, error={DescribeJson(errorElement)}");
        }

        private static string DescribeJson(JsonElement element)
        {
            return element.ValueKind == JsonValueKind.Undefined ? "<missing>" : element.GetRawText();
        }

        /// <summary>
        /// Grace period check: without any network traffic, re-verifies the
        /// signed session captured at activation and fails once the session
        /// TTL (the grace period) has expired.
        /// </summary>
        private void GracePeriodCheck()
        {
            string? rawPayloadB64;
            string? signature;
            long? expiresIn;

            lock (_lock)
            {
                rawPayloadB64 = _rawPayloadB64;
                signature = _signature;
                expiresIn = _sessionExpiresIn;
            }

            if (string.IsNullOrEmpty(rawPayloadB64) || string.IsNullOrEmpty(signature))
            {
                throw new InvalidOperationException("missing_local_verification_state");
            }

            VerifySignature(rawPayloadB64, signature);

            if (expiresIn is null)
            {
                throw new InvalidOperationException("missing_session_expiry");
            }

            var now = DateTimeOffset.UtcNow.ToUnixTimeSeconds();
            if (now < expiresIn.Value)
            {
                return;
            }
            throw new AuthForgeException("session_expired");
        }

        private void ValidateAndStore(string licenseKey)
        {
            var body = new Dictionary<string, object?>
            {
                ["appId"] = AppId,
                ["appSecret"] = AppSecret,
                ["licenseKey"] = licenseKey,
                ["hwid"] = _hwid,
                ["nonce"] = GenerateNonce(),
            };
            if (TtlSeconds.HasValue)
            {
                body["ttlSeconds"] = TtlSeconds.Value;
            }
            // A network failure throws here; Login() reports it once, as login_failed.
            var responseObj = PostJson("/auth/validate", body);
            var expectedNonce = body.TryGetValue("nonce", out var usedNonce) ? (usedNonce?.ToString() ?? string.Empty) : string.Empty;
            ApplySignedResponse(responseObj, expectedNonce, licenseKey, "validate");
        }

        private sealed class ParsedValidateSession
        {
            public string SessionToken { get; set; } = string.Empty;
            public long ExpiresIn { get; set; }
            public string RawPayloadB64 { get; set; } = string.Empty;
            public string Signature { get; set; } = string.Empty;
            public string? KeyId { get; set; }
            public string? SessionExpiresAt { get; set; }
            public bool LicenseExpirationPresent { get; set; }
            public string? LicenseExpiresAt { get; set; }
            public int? MaxHwidSlots { get; set; }
            public int? HwidCount { get; set; }
            public string? LicenseLabel { get; set; }
            public Dictionary<string, JsonElement> PayloadJson { get; set; } = new(StringComparer.Ordinal);
        }

        private ParsedValidateSession ParseSignedValidateResponse(
            Dictionary<string, JsonElement> responseObj,
            string expectedNonce)
        {
            responseObj.TryGetValue("status", out var statusElement);
            if (!IsSuccessStatus(statusElement))
            {
                throw new ArgumentException(ExtractServerError(responseObj));
            }

            var rawPayloadB64 = RequireStr(responseObj, "payload");
            var signature = RequireStr(responseObj, "signature");
            var payloadJson = DecodePayloadJson(rawPayloadB64);

            var receivedNonce = payloadJson.TryGetValue("nonce", out var nonceElement)
                ? (nonceElement.ToString() ?? string.Empty).Trim()
                : string.Empty;
            if (!string.Equals(receivedNonce, expectedNonce, StringComparison.Ordinal))
            {
                throw new ArgumentException("nonce_mismatch");
            }

            VerifySignature(rawPayloadB64, signature);

            var sessionToken = payloadJson.TryGetValue("sessionToken", out var sessionTokenElement)
                ? (sessionTokenElement.ToString() ?? string.Empty).Trim()
                : string.Empty;
            if (string.IsNullOrEmpty(sessionToken))
            {
                throw new ArgumentException("missing_sessionToken");
            }

            var expiresFromToken = ExtractExpiresInFromSessionToken(sessionToken);
            long? expiresFromPayload = null;
            if (payloadJson.TryGetValue("expiresIn", out var expiresElement) && expiresElement.ValueKind != JsonValueKind.Null)
            {
                expiresFromPayload = ConvertToInt64(expiresElement);
            }

            var expiresIn = expiresFromToken ?? expiresFromPayload;
            if (expiresIn is null)
            {
                throw new ArgumentException("missing_expiresIn");
            }

            string? sessionExpiresAt = null;
            if (payloadJson.TryGetValue("sessionExpiresAt", out var sea) && sea.ValueKind == JsonValueKind.String)
            {
                sessionExpiresAt = sea.GetString();
            }

            var licenseExpirationPresent = payloadJson.TryGetValue("licenseExpiresAt", out var lee);
            string? licenseExpiresAt = null;
            if (licenseExpirationPresent)
            {
                licenseExpiresAt = lee.ValueKind == JsonValueKind.Null ? null : lee.GetString();
            }

            int? maxHwidSlots = null;
            if (payloadJson.TryGetValue("maxHwidSlots", out var mh) && mh.ValueKind != JsonValueKind.Null)
            {
                maxHwidSlots = ConvertToInt32Nullable(mh);
            }

            int? hwidCount = null;
            if (payloadJson.TryGetValue("hwidCount", out var hc) && hc.ValueKind != JsonValueKind.Null)
            {
                hwidCount = ConvertToInt32Nullable(hc);
            }

            string? licenseLabel = null;
            if (payloadJson.TryGetValue("licenseLabel", out var ll) && ll.ValueKind == JsonValueKind.String)
            {
                licenseLabel = ll.GetString();
            }

            return new ParsedValidateSession
            {
                SessionToken = sessionToken,
                ExpiresIn = expiresIn.Value,
                RawPayloadB64 = rawPayloadB64,
                Signature = signature,
                KeyId = responseObj.TryGetValue("keyId", out var keyIdElement) ? keyIdElement.ToString() : null,
                SessionExpiresAt = sessionExpiresAt,
                LicenseExpirationPresent = licenseExpirationPresent,
                LicenseExpiresAt = licenseExpiresAt,
                MaxHwidSlots = maxHwidSlots,
                HwidCount = hwidCount,
                LicenseLabel = licenseLabel,
                PayloadJson = payloadJson,
            };
        }

        /// <summary>
        /// Stores a verified session. With <paramref name="expectedGeneration"/>
        /// (heartbeat refresh) the write is skipped if the session was logged out
        /// or replaced since the request started; without it (validate) a new
        /// session generation begins.
        /// </summary>
        private void ApplySignedResponse(
            Dictionary<string, JsonElement> responseObj,
            string expectedNonce,
            string? licenseKey,
            string context,
            int? expectedGeneration = null)
        {
            var parsed = ParseSignedValidateResponse(responseObj, expectedNonce);
            _ = context;

            lock (_lock)
            {
                if (expectedGeneration is null)
                {
                    _sessionGeneration++;
                }
                else if (expectedGeneration.Value != _sessionGeneration)
                {
                    return;
                }

                if (licenseKey is not null)
                {
                    _licenseKey = licenseKey;
                }

                _sessionToken = parsed.SessionToken;
                _sessionExpiresIn = parsed.ExpiresIn;
                _lastNonce = expectedNonce;
                _rawPayloadB64 = parsed.RawPayloadB64;
                _signature = parsed.Signature;
                _keyId = parsed.KeyId;
                _sessionData = ConvertToObjectMap(parsed.PayloadJson);
                _appVariables = parsed.PayloadJson.TryGetValue("appVariables", out var appVarsElement)
                    ? ConvertJsonElementObject(appVarsElement)
                    : null;
                _licenseVariables = parsed.PayloadJson.TryGetValue("licenseVariables", out var licenseVarsElement)
                    ? ConvertJsonElementObject(licenseVarsElement)
                    : null;
                _authenticated = true;
                _sessionKind = SessionKind.Online;
            }
        }

        private Dictionary<string, JsonElement> PostJson(string path, Dictionary<string, object?> data)
        {
            var url = $"{ApiBaseUrl}{path}";
            var body = new Dictionary<string, object?>(data, StringComparer.Ordinal);
            var rateRetryDelays = new[] { 2, 5 };
            var networkRetried = false;
            var rateAttempt = 0;

            while (true)
            {
                if (rateAttempt > 0 && body.ContainsKey("nonce"))
                {
                    body["nonce"] = GenerateNonce();
                    data["nonce"] = body["nonce"];
                }

                var payloadBytes = JsonSerializer.SerializeToUtf8Bytes(body, CompactJsonOptions);
                using var request = new HttpRequestMessage(HttpMethod.Post, url)
                {
                    Content = new ByteArrayContent(payloadBytes),
                };
                request.Content.Headers.ContentType = new System.Net.Http.Headers.MediaTypeHeaderValue("application/json");

                try
                {
                    using var response = _httpClient.SendAsync(request).GetAwaiter().GetResult();
                    var statusCode = (int)response.StatusCode;
                    var rawResponse = response.Content.ReadAsStringAsync().GetAwaiter().GetResult();
                    Dictionary<string, JsonElement> parsed;
                    try
                    {
                        parsed = ParseResponseObject(rawResponse);
                    }
                    catch (Exception ex)
                    {
                        if (statusCode >= 400)
                        {
                            throw new AuthForgeException($"http_error_{statusCode}", $"http_error_{statusCode}", ex);
                        }
                        throw;
                    }
                    // no_credits / app_burn_cap_reached / demo_quota_exceeded also use
                    // HTTP 429 but are not worth retrying; only retry a genuine rate limit.
                    var serverError = ExtractServerError(parsed);
                    var isRateLimited = serverError == "rate_limited"
                        || (statusCode == 429 && serverError == "unknown_error");
                    if (isRateLimited && rateAttempt < rateRetryDelays.Length)
                    {
                        SleepFn(TimeSpan.FromSeconds(rateRetryDelays[rateAttempt]));
                        rateAttempt++;
                        continue;
                    }
                    return parsed;
                }
                catch (Exception ex) when (ex is HttpRequestException || ex is TaskCanceledException)
                {
                    if (!networkRetried)
                    {
                        networkRetried = true;
                        SleepFn(TimeSpan.FromSeconds(2));
                        continue;
                    }
                    var code = ex is TaskCanceledException ? "timeout" : "network_error";
                    throw new AuthForgeException(code, $"url_error: {ex.Message}", ex);
                }
            }
        }

        /// <summary>Delay used between request retries; replaceable in tests.</summary>
        internal Action<TimeSpan> SleepFn { get; set; } = Thread.Sleep;

        /// <summary>Process exit used when there is no <see cref="OnFailure"/>; replaceable in tests.</summary>
        internal Action<int> ExitFn { get; set; } = Environment.Exit;

        /// <summary>Writes the stderr warning for transient failures without <see cref="OnFailure"/>; replaceable in tests.</summary>
        internal Action<string> WarnFn { get; set; } = message => Console.Error.WriteLine(message);

        private static Dictionary<string, JsonElement> ParseResponseObject(string rawResponse)
        {
            JsonDocument document;
            try
            {
                document = JsonDocument.Parse(rawResponse);
            }
            catch (JsonException ex)
            {
                throw new ArgumentException("invalid_json_response", ex);
            }

            using (document)
            {
                if (document.RootElement.ValueKind != JsonValueKind.Object)
                {
                    throw new ArgumentException("response_not_json_object");
                }

                var result = new Dictionary<string, JsonElement>(StringComparer.Ordinal);
                foreach (var property in document.RootElement.EnumerateObject())
                {
                    result[property.Name] = property.Value.Clone();
                }

                return result;
            }
        }

        // HWID v2: sha256("authforge-hwid-v2|" + appId + "|" + machineId), where machineId is
        // the OS machine id (macOS IOPlatformUUID, Linux /etc/machine-id, Windows MachineGuid).
        // Every SDK derives the same value; conformance is pinned by hwid_vectors.json.
        internal const string HwidV2Prefix = "authforge-hwid-v2|";
        private const int MachineIdCommandTimeoutMs = 2000;
        private static readonly string[] LinuxMachineIdPaths = { "/etc/machine-id", "/var/lib/dbus/machine-id" };
        private static readonly Regex IoregPlatformUuidRegex = new Regex("\"IOPlatformUUID\"\\s*=\\s*\"([^\"]+)\"", RegexOptions.CultureInvariant);
        private static readonly char[] AsciiWhitespace = { ' ', '\t', '\r', '\n' };

        private string ComputeHwid()
        {
            string machineId;
            try
            {
                machineId = ReadOsMachineId() ?? ("legacy:" + ComputeLegacyFingerprint());
            }
            catch
            {
                machineId = "legacy:" + ComputeLegacyFingerprint();
            }
            return HwidFromMachineId(AppId, machineId);
        }

        /// <summary>Derive the HWID from an already-normalized machine id (or a <c>legacy:</c> fallback id).</summary>
        internal static string HwidFromMachineId(string appId, string machineId)
        {
            byte[] hash;
            using (var sha256 = SHA256.Create())
            {
                hash = sha256.ComputeHash(Encoding.UTF8.GetBytes(HwidV2Prefix + appId + "|" + machineId));
            }
            return ToHexLower(hash);
        }

        /// <summary>Trim and lowercase an OS machine id; <c>null</c> when it is not a usable id.</summary>
        internal static string? NormalizeMachineId(string? raw)
        {
            if (raw is null)
            {
                return null;
            }

            var value = raw.Trim(AsciiWhitespace).ToLowerInvariant();
            if (value.Length < 8 || value.Length > 128)
            {
                return null;
            }

            var hasSignificant = false;
            foreach (var c in value)
            {
                var isHex = (c >= '0' && c <= '9') || (c >= 'a' && c <= 'f');
                if (!isHex && c != '-')
                {
                    return null;
                }
                if (c != '0' && c != '-')
                {
                    hasSignificant = true;
                }
            }

            return hasSignificant ? value : null;
        }

        /// <summary>Extract IOPlatformUUID from <c>ioreg -rd1 -c IOPlatformExpertDevice</c> output.</summary>
        internal static string? ParseIoregPlatformUuid(string? output)
        {
            if (output is null)
            {
                return null;
            }

            var match = IoregPlatformUuidRegex.Match(output);
            return match.Success ? match.Groups[1].Value : null;
        }

        /// <summary>Extract MachineGuid from <c>reg.exe query ... /v MachineGuid</c> output.</summary>
        internal static string? ParseRegQueryMachineGuid(string? output)
        {
            if (output is null)
            {
                return null;
            }

            foreach (var line in output.Split('\n'))
            {
                var tokens = line.Split(AsciiWhitespace, StringSplitOptions.RemoveEmptyEntries);
                if (tokens.Length >= 3
                    && string.Equals(tokens[0], "MachineGuid", StringComparison.OrdinalIgnoreCase)
                    && tokens[1] == "REG_SZ")
                {
                    return tokens[2];
                }
            }

            return null;
        }

        private static string? ReadOsMachineId()
        {
            try
            {
                if (RuntimeInformation.IsOSPlatform(OSPlatform.OSX))
                {
                    return NormalizeMachineId(ParseIoregPlatformUuid(
                        RunMachineIdCommand("/usr/sbin/ioreg", "-rd1 -c IOPlatformExpertDevice")));
                }

                if (RuntimeInformation.IsOSPlatform(OSPlatform.Linux))
                {
                    foreach (var file in LinuxMachineIdPaths)
                    {
                        try
                        {
                            var id = NormalizeMachineId(System.IO.File.ReadAllText(file));
                            if (id != null)
                            {
                                return id;
                            }
                        }
                        catch
                        {
                            // Missing or unreadable: try the next source.
                        }
                    }

                    return null;
                }

                if (RuntimeInformation.IsOSPlatform(OSPlatform.Windows))
                {
                    var systemRoot = Environment.GetEnvironmentVariable("SystemRoot");
                    if (string.IsNullOrEmpty(systemRoot))
                    {
                        systemRoot = @"C:\Windows";
                    }
                    var regExe = System.IO.Path.Combine(systemRoot, "System32", "reg.exe");
                    var output = RunMachineIdCommand(
                        regExe,
                        "query \"HKLM\\SOFTWARE\\Microsoft\\Cryptography\" /v MachineGuid /reg:64");
                    return NormalizeMachineId(ParseRegQueryMachineGuid(output));
                }
            }
            catch
            {
                // Fall through to the legacy fingerprint.
            }

            return null;
        }

        /// <summary>Runs a command and returns its full stdout, or <c>null</c> on any failure.</summary>
        private static string? RunMachineIdCommand(string fileName, string arguments)
        {
            try
            {
                var startInfo = new ProcessStartInfo
                {
                    FileName = fileName,
                    Arguments = arguments,
                    RedirectStandardOutput = true,
                    RedirectStandardError = true,
                    UseShellExecute = false,
                    CreateNoWindow = true,
                };

                using var process = Process.Start(startInfo);
                if (process is null)
                {
                    return null;
                }

                // Read asynchronously so a full pipe buffer cannot block the child past the timeout.
                // Stderr is drained and discarded.
                var stdoutTask = process.StandardOutput.ReadToEndAsync();
                _ = process.StandardError.ReadToEndAsync();
                if (!process.WaitForExit(MachineIdCommandTimeoutMs))
                {
                    try
                    {
                        process.Kill();
                    }
                    catch
                    {
                        // Ignore kill failures.
                    }

                    return null;
                }

                if (!stdoutTask.Wait(MachineIdCommandTimeoutMs))
                {
                    return null;
                }

                return process.ExitCode == 0 ? stdoutTask.Result : null;
            }
            catch
            {
                return null;
            }
        }

        // Pre-2.0 fingerprint, kept only as the fallback when no OS machine id is readable.
        private string ComputeLegacyFingerprint()
        {
            var mac = SafeMacAddress();
            var cpu = SafeCpuInfo();
            var disk = SafeDiskSerial();
            var material = $"mac:{mac}|cpu:{cpu}|disk:{disk}";
            byte[] hash;
            using (var sha256 = SHA256.Create())
            {
                hash = sha256.ComputeHash(Encoding.UTF8.GetBytes(material));
            }
            return ToHexLower(hash);
        }

        private string ResolveHwid(string? hwidOverride)
        {
            var trimmed = (hwidOverride ?? string.Empty).Trim();
            return trimmed.Length > 0 ? trimmed : ComputeHwid();
        }

        private string SafeMacAddress()
        {
            try
            {
                foreach (var networkInterface in NetworkInterface.GetAllNetworkInterfaces())
                {
                    var bytes = networkInterface.GetPhysicalAddress().GetAddressBytes();
                    if (bytes.Length > 0)
                    {
                        return BitConverter.ToString(bytes).Replace("-", string.Empty).ToLowerInvariant();
                    }
                }

                return "mac-unavailable";
            }
            catch
            {
                return "mac-unavailable";
            }
        }

        private string SafeCpuInfo()
        {
            try
            {
                var value = $"{Environment.ProcessorCount}-{RuntimeInformation.ProcessArchitecture}";
                return string.IsNullOrWhiteSpace(value) ? "cpu-unavailable" : value;
            }
            catch
            {
                return "cpu-unavailable";
            }
        }

        private string SafeDiskSerial()
        {
            var system = RuntimeInformation.OSDescription.ToLowerInvariant();
            try
            {
                if (system.Contains("windows", StringComparison.Ordinal))
                {
                    return RunCommand("wmic", "diskdrive get serialnumber");
                }

                if (system.Contains("linux", StringComparison.Ordinal))
                {
                    var outText = RunCommand("lsblk", "-ndo SERIAL");
                    if (!string.IsNullOrWhiteSpace(outText))
                    {
                        return outText;
                    }

                    return RunCommand("udevadm", "info --query=property --name=sda");
                }

                if (system.Contains("darwin", StringComparison.Ordinal) || RuntimeInformation.IsOSPlatform(OSPlatform.OSX))
                {
                    return RunCommand("system_profiler", "SPStorageDataType");
                }
            }
            catch
            {
                return "disk-unavailable";
            }

            return "disk-unavailable";
        }

        private static string RunCommand(string fileName, string arguments)
        {
            try
            {
                var startInfo = new ProcessStartInfo
                {
                    FileName = fileName,
                    Arguments = arguments,
                    RedirectStandardOutput = true,
                    RedirectStandardError = true,
                    UseShellExecute = false,
                    CreateNoWindow = true,
                };

                using var process = Process.Start(startInfo);
                if (process is null)
                {
                    return "unavailable";
                }

                if (!process.WaitForExit(2000))
                {
                    try
                    {
                        process.Kill();
                    }
                    catch
                    {
                        // Ignore kill failures and return unavailable.
                    }

                    return "unavailable";
                }

                var output = process.StandardOutput.ReadToEnd();
                var cleaned = string.Join(" ", (output ?? string.Empty).Split((char[]?)null, StringSplitOptions.RemoveEmptyEntries));
                return string.IsNullOrEmpty(cleaned) ? "empty" : (cleaned.Length > 256 ? cleaned.Substring(0, 256) : cleaned);
            }
            catch
            {
                return "unavailable";
            }
        }

        private static Dictionary<string, JsonElement> DecodePayloadJson(string payloadB64)
        {
            var payloadBytes = DecodeBase64Any(payloadB64);
            JsonDocument doc;
            try
            {
                doc = JsonDocument.Parse(payloadBytes);
            }
            catch (Exception ex)
            {
                throw new ArgumentException("invalid_payload_json", ex);
            }

            using (doc)
            {
                if (doc.RootElement.ValueKind != JsonValueKind.Object)
                {
                    throw new ArgumentException("payload_not_json_object");
                }

                var result = new Dictionary<string, JsonElement>(StringComparer.Ordinal);
                foreach (var property in doc.RootElement.EnumerateObject())
                {
                    result[property.Name] = property.Value.Clone();
                }

                return result;
            }
        }

        private static byte[] DecodeBase64Any(string value)
        {
            var padded = AddBase64Padding(value);
            try
            {
                return Convert.FromBase64String(padded);
            }
            catch
            {
                var normalized = padded.Replace('-', '+').Replace('_', '/');
                return Convert.FromBase64String(normalized);
            }
        }

        private static JsonDocument? TryDecodeSessionTokenBody(string sessionToken)
        {
            var parts = sessionToken.Split('.');
            if (parts.Length < 2)
            {
                return null;
            }

            var padded = AddBase64Padding(parts[0]);
            try
            {
                var normalized = padded.Replace('-', '+').Replace('_', '/');
                var decoded = Convert.FromBase64String(normalized);
                var doc = JsonDocument.Parse(decoded);
                if (doc.RootElement.ValueKind != JsonValueKind.Object)
                {
                    doc.Dispose();
                    return null;
                }
                return doc;
            }
            catch
            {
                return null;
            }
        }

        private static long? ExtractExpiresInFromSessionToken(string sessionToken)
        {
            using var doc = TryDecodeSessionTokenBody(sessionToken);
            if (doc is null)
            {
                return null;
            }

            if (!doc.RootElement.TryGetProperty("exp", out var expiresInElement))
            {
                return null;
            }

            try
            {
                return ConvertToInt64(expiresInElement);
            }
            catch
            {
                return null;
            }
        }

        private static string AddBase64Padding(string text)
        {
            var remainder = text.Length % 4;
            if (remainder == 0)
            {
                return text;
            }

            return text + new string('=', 4 - remainder);
        }

        private void VerifySignature(string rawPayloadB64, string signature)
        {
            byte[] signatureBytes;
            try
            {
                signatureBytes = Convert.FromBase64String(signature);
            }
            catch (FormatException ex)
            {
                throw new ArgumentException("invalid_signature", ex);
            }

            // Walk the trust list and accept on first match. Allows callers
            // to keep verifying during a server-side key rotation by pinning
            // both the previous and the current key.
            var payloadBytes = Encoding.UTF8.GetBytes(rawPayloadB64);
            foreach (var key in _verifyPublicKeys)
            {
                var verifier = new Ed25519Signer();
                verifier.Init(forSigning: false, key);
                verifier.BlockUpdate(payloadBytes, 0, payloadBytes.Length);
                if (verifier.VerifySignature(signatureBytes))
                {
                    return;
                }
            }
            throw new ArgumentException("signature_mismatch");
        }

        /// <summary>
        /// Integration test hook: when set, returned by <see cref="GenerateNonce"/> (same assembly only).
        /// </summary>
        internal static string? TestNonceOverride { get; set; }

        private static string GenerateNonce()
        {
            if (!string.IsNullOrEmpty(TestNonceOverride))
            {
                return TestNonceOverride!;
            }

            var bytes = new byte[16];
            using (var random = RandomNumberGenerator.Create())
            {
                random.GetBytes(bytes);
            }
            return ToHexStringCompat(bytes).ToLowerInvariant();
        }

        private static bool IsSuccessStatus(JsonElement status)
        {
            if (status.ValueKind == JsonValueKind.True)
            {
                return true;
            }

            if (status.ValueKind == JsonValueKind.False || status.ValueKind == JsonValueKind.Null || status.ValueKind == JsonValueKind.Undefined)
            {
                return false;
            }

            var value = (status.ToString() ?? string.Empty).Trim().ToLowerInvariant();
            return value == "ok" || value == "success" || value == "valid" || value == "true" || value == "1";
        }

        private static string RequireStr(Dictionary<string, JsonElement> obj, string key)
        {
            if (!obj.TryGetValue(key, out var value) || value.ValueKind == JsonValueKind.Null || value.ValueKind == JsonValueKind.Undefined)
            {
                throw new ArgumentException($"missing_{key}");
            }

            var text = value.ToString() ?? string.Empty;
            if (text.Length == 0)
            {
                throw new ArgumentException($"empty_{key}");
            }

            return text;
        }

        private void Fail(string reason, Exception? ex = null)
        {
            if (OnFailure is not null)
            {
                try
                {
                    OnFailure(reason, ex);
                    return;
                }
                catch
                {
                    // Match Python behavior: callback failure falls through to exit.
                }
            }

            ExitFn(1);
        }

        private string ExtractServerError(Dictionary<string, JsonElement> responseObj)
        {
            if (responseObj.TryGetValue("error", out var errorElement))
            {
                var error = (errorElement.ToString() ?? string.Empty).Trim().ToLowerInvariant();
                if (_knownServerErrors.Contains(error) || ServerErrorCodeRegex.IsMatch(error))
                {
                    return error;
                }
            }

            if (responseObj.TryGetValue("status", out var statusElement))
            {
                var status = (statusElement.ToString() ?? string.Empty).Trim().ToLowerInvariant();
                if (_knownServerErrors.Contains(status))
                {
                    return status;
                }
            }

            return "unknown_error";
        }

        /// <summary>
        /// Stops the background thread and clears all session state. Safe to
        /// call from <see cref="OnFailure"/> (including on the heartbeat thread):
        /// it signals the thread to stop and never waits for it.
        /// </summary>
        public void Logout()
        {
            lock (_lock)
            {
                ClearSessionLocked();
            }
        }

        private void ClearSessionLocked()
        {
            _sessionGeneration++;
            _heartbeatStopSignal?.Set();
            _heartbeatStopSignal = null;
            _heartbeatStarted = false;
            _heartbeatThread = null;
            _licenseKey = null;
            _sessionToken = null;
            _sessionExpiresIn = null;
            _lastNonce = null;
            _rawPayloadB64 = null;
            _signature = null;
            _keyId = null;
            _sessionData = null;
            _appVariables = null;
            _licenseVariables = null;
            _authenticated = false;
            _sessionKind = null;
            _offlineLicense = null;
        }

        public bool IsAuthenticated()
        {
            lock (_lock)
            {
                switch (_sessionKind)
                {
                    case SessionKind.Online:
                        return _authenticated && !string.IsNullOrEmpty(_sessionToken);
                    case SessionKind.Offline:
                        return _authenticated && _offlineLicense != null;
                    case null:
                        return false;
                    default:
                        throw new InvalidOperationException($"unhandled session kind: {_sessionKind}");
                }
            }
        }

        /// <summary>
        /// <see cref="SessionKind.Online"/> after <see cref="Login"/>,
        /// <see cref="SessionKind.Offline"/> after <see cref="LoginFromFile"/>,
        /// <c>null</c> when logged out.
        /// </summary>
        public SessionKind? GetSessionKind()
        {
            lock (_lock)
            {
                return _sessionKind;
            }
        }

        public Dictionary<string, object?>? GetSessionData()
        {
            lock (_lock)
            {
                return _sessionData is null ? null : new Dictionary<string, object?>(_sessionData, StringComparer.Ordinal);
            }
        }

        public Dictionary<string, object?>? GetAppVariables()
        {
            lock (_lock)
            {
                return _appVariables is null ? null : new Dictionary<string, object?>(_appVariables, StringComparer.Ordinal);
            }
        }

        public Dictionary<string, object?>? GetLicenseVariables()
        {
            lock (_lock)
            {
                return _licenseVariables is null ? null : new Dictionary<string, object?>(_licenseVariables, StringComparer.Ordinal);
            }
        }

        private static int? ConvertToInt32Nullable(JsonElement element)
        {
            try
            {
                var v = ConvertToInt64(element);
                if (v > int.MaxValue || v < int.MinValue)
                {
                    return null;
                }
                return (int)v;
            }
            catch (ArgumentException)
            {
                return null;
            }
            catch (OverflowException)
            {
                return null;
            }
            catch (FormatException)
            {
                return null;
            }
        }

        private static long ConvertToInt64(JsonElement element)
        {
            if (element.ValueKind == JsonValueKind.Number && element.TryGetInt64(out var int64Value))
            {
                return int64Value;
            }

            var text = element.ToString();
            if (text is null)
            {
                throw new ArgumentException("invalid_integer_value");
            }

            return long.Parse(text, NumberStyles.Integer, CultureInfo.InvariantCulture);
        }

        private static string ToHexLower(byte[] bytes)
        {
            return ToHexStringCompat(bytes).ToLowerInvariant();
        }

        private static string ToHexStringCompat(byte[] bytes)
        {
            return BitConverter.ToString(bytes).Replace("-", string.Empty);
        }

        private static Dictionary<string, object?>? ConvertJsonElementObject(JsonElement element)
        {
            if (element.ValueKind != JsonValueKind.Object)
            {
                return null;
            }

            return JsonSerializer.Deserialize<Dictionary<string, object?>>(element.GetRawText());
        }

        private static Dictionary<string, object?> ConvertToObjectMap(Dictionary<string, JsonElement> source)
        {
            var result = new Dictionary<string, object?>(StringComparer.Ordinal);
            foreach (var entry in source)
            {
                result[entry.Key] = JsonSerializer.Deserialize<object?>(entry.Value.GetRawText());
            }
            return result;
        }
    }

    public sealed class ValidateLicenseResult
    {
        public bool Valid { get; set; }
        public string? ErrorCode { get; set; }
        public Exception? Error { get; set; }
        public string? SessionToken { get; set; }
        public long? ExpiresIn { get; set; }
        public Dictionary<string, object?>? SessionData { get; set; }
        public Dictionary<string, object?>? AppVariables { get; set; }
        public Dictionary<string, object?>? LicenseVariables { get; set; }
        public string? KeyId { get; set; }
        /// <summary>ISO 8601 session expiry when the server includes <c>sessionExpiresAt</c>.</summary>
        public string? SessionExpiresAt { get; set; }
        /// <summary>True when the signed payload included <c>licenseExpiresAt</c> (lifetime keys use JSON null).</summary>
        public bool LicenseExpirationPresent { get; set; }
        /// <summary>License expiry when <see cref="LicenseExpirationPresent"/>; null for lifetime keys.</summary>
        public string? LicenseExpiresAt { get; set; }
        public int? MaxHwidSlots { get; set; }
        public int? HwidCount { get; set; }
        /// <summary>Optional dashboard label from the signed payload.</summary>
        public string? LicenseLabel { get; set; }
    }
}