feat+fix: address issue #8 (diagnostic + rate-limit + env-file)

Addresses all three asks from GitHub issue #8 plus a follow-up retry on
the documented sandbox rate-limit surface.

== Ask 1: log raw response body on meta-failure throws ==

CERTInextClient.cs throws "CERTInext ... failed: <ErrorMessage>. See
gateway logs for details." on every non-success meta block, but most
sites had no Logger.LogXxx call before the throw — the "see gateway
logs" instruction was misleading because no detail was ever logged.

Added a shared LogApiFailure(operationContext, resp, errorCode, errorMsg)
helper that emits a structured LogWarning capturing HTTP status, the
CERTInext error code + message, and a 4 KB-capped raw response body.
Wired into every meta-failure throw site:
  - ValidateCredentials, PlaceOrderAsync, SubmitCsrAsync (HTTP fail),
    TrackOrderAsync, DownloadCertificateAsync, RevokeCertificateAsync,
    VerifyDcvAsync, GetDcvAsync.

The exception text is unchanged (kept sanitized for the gateway UI per
the prior C2 audit finding), but operators now actually have the raw
body in gateway logs to diagnose. Closes the audit's deferred C2 item.

== Ask 2: Troubleshooting section ==

New docsource/overview.md + mirrored "Troubleshooting" section in
README.md covering:
  - "Inactive Account User." as a sandbox rate-limit surface
  - Enrollment returning EXTERNALVALIDATION (deferred to next sync)
  - EMS-956 from GetDcv (deferred to next sync)
  - Issue #7 type-load failure (closed in v1.0)

== Ask 3: LoadEnvFile quote stripping ==

IntegrationTestFixture.LoadEnvFile passed quoted env values through with
the quote characters included, so:
  CERTINEXT_REQUESTOR_NAME="Keyfactor Plugin Test"
was sent to CERTInext as the 23-char literal `"Keyfactor Plugin Test"`.
The integration tests have been sending the literal quotes for the
entire project history.

Extracted the value-parsing into IntegrationTestFixture.ParseEnvValue
(internal static), added matching-pair double/single quote stripping
per the reporter's snippet, and pinned the contract with 13 unit tests
in IntegrationTestFixtureTests covering quoted, unquoted, whitespace,
mismatched-quote, empty, and embedded-quote cases.

== Follow-up: exponential-backoff retry on rate-limit surface ==

PlaceOrderAsync now auto-retries when meta.ErrorMessage matches the
documented "Inactive Account User." rate-limit surface (case-insensitive
substring match via IsRateLimitSurface). Up to 5 attempts with exponential
backoff + ±25% jitter — nominal delays 1s / 2s / 4s / 8s / 16s, max
total wait ~31s. Each retry refreshes the meta block so txn IDs stay
unique. After all attempts exhaust, the original exception is propagated
unchanged so a genuinely-inactive account surfaces identically to today.

ComputeRateLimitBackoffSeconds + IsRateLimitSurface are exposed internal
so unit tests can pin both the predicate (15 inline-data cases) and the
backoff schedule (50 samples per attempt window).

== Verification ==

- Release build: 0 warnings, 0 errors.
- Unit tests: 171/171 pass (156 prior + 15 new in RateLimitRetryTests
  + IntegrationTestFixtureTests).
- Live ping/sync against the sandbox still authenticates.
- Issue #7's CERTInextCAPluginPublicSurfaceTests still passes — the
  refactor of PlaceOrderAsync didn't expose any v3.3-only types.

Author: spbsoluble

CERTInext.IntegrationTests/IntegrationTestFixture.cs

@@ -159,7 +159,7 @@ private static Dictionary<string, string> LoadEnvFile(string path)
                         continue;
 
                     string key = line.Substring(0, idx).Trim();
-                    string val = line.Substring(idx + 1).Trim();
+                    string val = ParseEnvValue(line.Substring(idx + 1));
                     result[key] = val;
                 }
             }
@@ -176,6 +176,28 @@ private static Dictionary<string, string> LoadEnvFile(string path)
             return result;
         }
 
+        /// <summary>
+        /// Parses a raw value from a <c>KEY=VALUE</c> env-file line: trims surrounding
+        /// whitespace, then strips a single pair of matching surrounding double or single
+        /// quotes if present.  Without quote stripping a line like
+        /// <c>CERTINEXT_REQUESTOR_NAME="Keyfactor Plugin Test"</c> would parse as the 24-char
+        /// literal <c>"Keyfactor Plugin Test"</c> (quotes included), diverging from any
+        /// other shell-style env consumer reading the same file.  See GitHub issue #8.
+        /// Exposed <c>internal</c> for direct unit-testing.
+        /// </summary>
+        internal static string ParseEnvValue(string rawValue)
+        {
+            if (rawValue is null) return string.Empty;
+            string val = rawValue.Trim();
+            if (val.Length >= 2 &&
+                ((val[0] == '"' && val[val.Length - 1] == '"') ||
+                 (val[0] == '\'' && val[val.Length - 1] == '\'')))
+            {
+                val = val.Substring(1, val.Length - 2);
+            }
+            return val;
+        }
+
         private static string GetEnvValue(Dictionary<string, string> env, string key)
         {
             return env.TryGetValue(key, out string val) ? val : string.Empty;

CERTInext.IntegrationTests/IntegrationTestFixtureTests.cs

@@ -0,0 +1,53 @@
+// Copyright 2024 Keyfactor
+// Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0
+// Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions
+// and limitations under the License.
+
+using FluentAssertions;
+using Xunit;
+
+namespace Keyfactor.Extensions.CAPlugin.CERTInext.IntegrationTests
+{
+    /// <summary>
+    /// Pure unit tests (no live-API dependency) for the env-file parser used by
+    /// <see cref="IntegrationTestFixture"/>.  See GitHub issue #8 — without quote
+    /// stripping, a shell-style quoted line was being parsed with the quote characters
+    /// included in the value.
+    /// </summary>
+    public class IntegrationTestFixtureTests
+    {
+        [Theory]
+        [InlineData("plain", "plain")]
+        [InlineData("  plain  ", "plain")]
+        [InlineData("\"Keyfactor Plugin Test\"", "Keyfactor Plugin Test")]
+        [InlineData("  \"Keyfactor Plugin Test\"  ", "Keyfactor Plugin Test")]
+        [InlineData("'single quoted'", "single quoted")]
+        [InlineData("\"\"", "")]               // empty quoted string
+        [InlineData("''", "")]                 // empty single-quoted
+        [InlineData("\"un-paired'", "\"un-paired'")] // mismatched quotes — leave alone
+        [InlineData("\"", "\"")]               // single naked quote, length<2 after trim — leave alone
+        [InlineData("", "")]
+        [InlineData("   ", "")]
+        public void ParseEnvValue_HandlesQuotingAndWhitespace(string input, string expected)
+        {
+            IntegrationTestFixture.ParseEnvValue(input).Should().Be(expected);
+        }
+
+        [Fact]
+        public void ParseEnvValue_NullInput_ReturnsEmptyString()
+        {
+            IntegrationTestFixture.ParseEnvValue(null).Should().Be(string.Empty);
+        }
+
+        [Fact]
+        public void ParseEnvValue_DoesNotStripEmbeddedQuotes()
+        {
+            // Quotes in the middle of the value must NOT be stripped; only matching
+            // outer wrappers count.
+            IntegrationTestFixture.ParseEnvValue("foo\"bar\"baz")
+                .Should().Be("foo\"bar\"baz");
+        }
+    }
+}

CERTInext.Tests/RateLimitRetryTests.cs

@@ -0,0 +1,64 @@
+// Copyright 2024 Keyfactor
+// Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0
+// Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions
+// and limitations under the License.
+
+using FluentAssertions;
+using Keyfactor.Extensions.CAPlugin.CERTInext.Client;
+using Xunit;
+
+namespace Keyfactor.Extensions.CAPlugin.CERTInext.Tests
+{
+    /// <summary>
+    /// Pure unit tests for the rate-limit-retry helpers in <see cref="CERTInextClient"/>.
+    /// Behavioral / end-to-end coverage of the retry loop itself lives in the WireMock
+    /// tests; here we pin the predicate and the backoff schedule.
+    /// </summary>
+    public class RateLimitRetryTests
+    {
+        [Theory]
+        [InlineData("Inactive Account User.", true)]                       // exact form from sandbox
+        [InlineData("inactive account user.", true)]                       // case-insensitive
+        [InlineData("INACTIVE ACCOUNT USER", true)]                        // case + missing period
+        [InlineData("Some preamble: Inactive Account User. Tail", true)]   // embedded substring
+        [InlineData("Active account user.", false)]                        // wrong polarity
+        [InlineData("Account is inactive", false)]                         // similar phrase, wrong wording
+        [InlineData("EMS-956 Invalid Request for this API.", false)]       // unrelated error
+        [InlineData("", false)]
+        [InlineData(null, false)]
+        public void IsRateLimitSurface_DetectsDocumentedPhraseOnly(string errorMessage, bool expected)
+        {
+            CERTInextClient.IsRateLimitSurface(errorMessage).Should().Be(expected);
+        }
+
+        [Theory]
+        [InlineData(1, 0.75, 1.25)]   // base = 1s, jittered ±25% ⇒ [0.75, 1.25]
+        [InlineData(2, 1.5, 2.5)]    // 2s × jitter
+        [InlineData(3, 3.0, 5.0)]    // 4s × jitter
+        [InlineData(4, 6.0, 10.0)]   // 8s × jitter
+        [InlineData(5, 12.0, 20.0)]  // 16s × jitter
+        public void ComputeRateLimitBackoffSeconds_ProducesExpectedRange(int attempt, double min, double max)
+        {
+            // Run several samples so jitter is exercised; every sample must fall inside
+            // the documented exponential ± 25% jitter window.
+            for (int i = 0; i < 50; i++)
+            {
+                double waitSeconds = CERTInextClient.ComputeRateLimitBackoffSeconds(attempt);
+                waitSeconds.Should().BeInRange(min, max,
+                    $"attempt {attempt} sample {i} must fall inside the documented backoff window");
+            }
+        }
+
+        [Fact]
+        public void ComputeRateLimitBackoffSeconds_ClampsAttemptsBelowOneToOne()
+        {
+            // Defensive: passing 0 or negative shouldn't produce zero / negative delay.
+            CERTInextClient.ComputeRateLimitBackoffSeconds(0)
+                .Should().BeInRange(0.75, 1.25);
+            CERTInextClient.ComputeRateLimitBackoffSeconds(-3)
+                .Should().BeInRange(0.75, 1.25);
+        }
+    }
+}