From 9002c679b9adf6c93697cbbccb66a752ea510f97 Mon Sep 17 00:00:00 2001 From: spbsoluble <1661003+spbsoluble@users.noreply.github.com> Date: Sat, 14 Nov 2026 12:50:13 -0800 Subject: [PATCH 01/11] fix(sync): resolve 'Order Fulfilled | Pending for Approver' report rows through Track Order The report row says fulfilled while the certificate status says pending; Track Order returns issued (live: 1125823297). Preferring certificateStatus reported the order as pending and never downloaded the certificate. That one shape (order maps issued, certificate maps pending) now maps to null so the sync asks Track Order, and the pair appears in UnmappedReportStatuses. Other disagreements keep their mapping. --- .../V2SyncUnmappedStatusSummaryTests.cs | 42 +++++++++++++++++++ CERTInext/CERTInextCAPlugin.cs | 17 +++++++- CHANGELOG.md | 1 + docsource/configuration.md | 2 +- 4 files changed, 59 insertions(+), 3 deletions(-) diff --git a/CERTInext.Tests/V2SyncUnmappedStatusSummaryTests.cs b/CERTInext.Tests/V2SyncUnmappedStatusSummaryTests.cs index d4000e3..df68eb1 100644 --- a/CERTInext.Tests/V2SyncUnmappedStatusSummaryTests.cs +++ b/CERTInext.Tests/V2SyncUnmappedStatusSummaryTests.cs @@ -69,5 +69,47 @@ public async Task Summary_ListsEachUnmappedPairWithCount_AndUntrackableCount() .And.Contain("UntrackableListedOrders=2") .And.Contain("Errors=0"); } + + [Theory] + // Live on 1125823297: the report says pending, Track Order says issued. + [InlineData("Order Fulfilled", "Pending for Approver", null)] + [InlineData("Order Fulfilled", "Approved by System", null)] + // Disagreements certificateStatus already resolves correctly keep their mapping (no Track call). + [InlineData("Order Accepted", "Certificate Revoked", (int)Keyfactor.PKI.Enums.EJBCA.EndEntityStatus.REVOKED)] + [InlineData("Order Accepted", "Certificate Downloaded", (int)Keyfactor.PKI.Enums.EJBCA.EndEntityStatus.GENERATED)] + [InlineData("Order Fulfilled", "Certificate Downloaded", (int)Keyfactor.PKI.Enums.EJBCA.EndEntityStatus.GENERATED)] + [InlineData("Order Accepted", "Pending for Approver", (int)Keyfactor.PKI.Enums.EJBCA.EndEntityStatus.EXTERNALVALIDATION)] + [InlineData("Order Fulfilled", null, (int)Keyfactor.PKI.Enums.EJBCA.EndEntityStatus.GENERATED)] + public void MapReportStatus_OrderFulfilledButCertificatePending_DefersToTrack( + string orderStatus, string certificateStatus, int? expected) + { + CERTInextCAPlugin.MapV2ReportStatusToDisposition(orderStatus, certificateStatus).Should().Be(expected); + } + + [Fact] + public async Task Sync_OrderFulfilledPendingForApprover_TracksOnce_EmitsIssuedWithCertificate() + { + using var capture = new PluginLogCapture(); + var mock = new Mock(); + mock.Setup(c => c.ListOrdersV2Async(It.IsAny(), It.IsAny(), It.IsAny(), It.IsAny())) + .Returns(Rows(Row("1125823297", "Order Fulfilled", "Pending for Approver"))); + mock.Setup(c => c.ResolveAndTrackOrderV2WithFamilyAsync("1125823297", It.IsAny())) + .ReturnsAsync((Constants.ApiV2.FamilySsl, new V2OrderStatusResponse { OrderId = "1125823297", Status = "issued" })); + mock.Setup(c => c.ResolveAndDownloadCertificateV2Async("1125823297", It.IsAny())) + .ReturnsAsync(new V2CertificateDownloadResponse { OrderId = "1125823297", SerialNumber = "AA", CertificatePem = MockCertificateData.FakePemCertificate }); + var config = new CERTInextConfig { UseV2Api = true, ApiUrl = "https://v2.certinext.io", OAuthClientId = "id", OAuthClientSecret = "s" }; + var plugin = new CERTInextCAPlugin(mock.Object, config); + var buffer = new BlockingCollection(10); + + await plugin.Synchronize(buffer, null, true, CancellationToken.None); + + var record = buffer.ToArray().Should().ContainSingle().Subject; + record.CARequestID.Should().Be("1125823297"); + record.Status.Should().Be((int)Keyfactor.PKI.Enums.EJBCA.EndEntityStatus.GENERATED); + record.Certificate.Should().StartWith("-----BEGIN CERTIFICATE-----"); + mock.Verify(c => c.ResolveAndTrackOrderV2WithFamilyAsync("1125823297", It.IsAny()), Times.Once); + capture.Lines(LogLevel.Information, "synchronization complete").Should().ContainSingle() + .Which.Should().Contain("UnmappedReportStatuses=[Order Fulfilled | Pending for Approver (1)]"); + } } } diff --git a/CERTInext/CERTInextCAPlugin.cs b/CERTInext/CERTInextCAPlugin.cs index 453c44e..94a8ed8 100644 --- a/CERTInext/CERTInextCAPlugin.cs +++ b/CERTInext/CERTInextCAPlugin.cs @@ -4026,11 +4026,24 @@ internal static bool ShouldDeferRecentOrder( /// internal static int? MapV2ReportStatusToDisposition(string orderStatus, string certificateStatus) { + bool certMapped = TryMapV2ReportDisplayStatus(certificateStatus, out int certDisposition); + bool orderMapped = TryMapV2ReportDisplayStatus(orderStatus, out int orderDisposition); + + // "Order Fulfilled | Pending for Approver" (seen live on 1125823297): the order says issued, + // the certificate says pending, and Track Order returns `issued`. Neither display string is + // authoritative, so return null and let the caller ask Track. Deliberately narrow: other + // disagreements (e.g. "Order Accepted | Certificate Revoked") are resolved correctly by + // certificateStatus and would only cost a Track call per row per pass. + if (certMapped && orderMapped + && orderDisposition == (int)EndEntityStatus.GENERATED + && certDisposition == (int)EndEntityStatus.EXTERNALVALIDATION) + return null; + // certificateStatus is the more specific signal when present — prefer it. - if (TryMapV2ReportDisplayStatus(certificateStatus, out int certDisposition)) + if (certMapped) return certDisposition; - if (TryMapV2ReportDisplayStatus(orderStatus, out int orderDisposition)) + if (orderMapped) return orderDisposition; return null; diff --git a/CHANGELOG.md b/CHANGELOG.md index a8f3fcd..24a655a 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -33,6 +33,7 @@ - fix(enroll): V2 order and CSR submissions are never auto-retried after a timeout, which could create duplicate orders (V1 since 1.0.1). - fix(sync): A V2 order that `/reports/orders` lists but Track Order finds in no product family (seen for every `On Hold | Setup Pending` row) is skipped with one Information line and counted as `UntrackableListedOrders` in the sync summary. It used to log an error with a stack trace and count toward the sync's 25% error-rate abort. - fix(sync): The V2 sync summary lists every `orderStatus | certificateStatus` pair from `/reports/orders` that the plugin didn't recognize, with counts (`UnmappedReportStatuses=[...]`), at Information. CERTInext doesn't document these values, so new ones now show up in ordinary logs. +- fix(sync): A V2 `/reports/orders` row that reads `Order Fulfilled | Pending for Approver` is resolved through Track Order, which returns `issued`, so the certificate is downloaded. It used to be reported as pending and never downloaded. Other disagreeing pairs, such as `Order Accepted | Certificate Revoked`, keep their mapping, because the certificate status is correct for them. - fix(v2): A V2 OAuth2 token request that gets no HTTP response (a dropped connection or other transport error) is retried twice, after 1 s and 3 s, so one network blip no longer fails an enrollment, a sync or a connector save. HTTP errors (400/401/403) are not retried, and order creates are still never retried. Token failures and other V2 calls with no response now log the transport detail (`TransportDetail=`: RestSharp's response status and the exception types and messages, with credentials removed) and include a short form in the error, instead of only `HttpStatus=0`. - fix(sync): The V2 sync also holds back pending and issued orders created in the last 120 s (`SyncRecentOrderGraceSeconds`, `0` disables), so an in-flight enrollment no longer fails with a duplicate key (V1 since 1.0.1). - fix(enroll): The in-call pickup wait is now capped at 75 s (it was 180 s) for V1 and V2, inside Command's roughly 100 s enrollment-call timeout, so a pickup that used its whole budget is no longer abandoned by Command. The 55 s default (`PickupRetries` 5, `PickupDelay` 10) is unaffected. diff --git a/docsource/configuration.md b/docsource/configuration.md index f8eae46..407b6fd 100644 --- a/docsource/configuration.md +++ b/docsource/configuration.md @@ -597,7 +597,7 @@ mapped to Failed — see the gateway trace log if certificates unexpectedly show **V2 synchronization:** - Synchronize pages through `/reports/orders`. Pages are capped at 100 rows, and `PageSize` is clamped to that. -- The report carries display strings (for example `Order Fulfilled`, `Certificate Downloaded`) rather than the status enum above. Recognized strings are mapped directly. Any other combination falls back to a live order-status call, so a new display value never silently misclassifies an order. If that call finds the order in no product family, as for every `On Hold | Setup Pending` row on the sandbox, the order is skipped for that pass and counted as `UntrackableListedOrders`; it isn't treated as an error. CERTInext doesn't document these display strings, so the sync summary names every pair it didn't recognize (`UnmappedReportStatuses=[...]`). Report a new pair so it can be mapped. +- The report carries display strings (for example `Order Fulfilled`, `Certificate Downloaded`) rather than the status enum above. Recognized strings are mapped directly. Any other combination falls back to a live order-status call, so a new display value never silently misclassifies an order. If that call finds the order in no product family, as for every `On Hold | Setup Pending` row on the sandbox, the order is skipped for that pass and counted as `UntrackableListedOrders`; it isn't treated as an error. CERTInext doesn't document these display strings, so the sync summary names every pair it didn't recognize (`UnmappedReportStatuses=[...]`). Report a new pair so it can be mapped. One known pair is deliberately left unmapped: `Order Fulfilled | Pending for Approver` (the order fulfilled, the certificate still pending). Track Order returns `issued` for it, so the plugin asks Track Order and downloads the certificate instead of reporting the order as pending. - Cancelled and rejected orders are skipped. Issued orders have their certificate chain downloaded. - CERTInext does not serve the certificate body of a revoked order. A revoked order is propagated as revoked only when the gateway already holds that certificate (the revocation date and reason come from a live status call). - Otherwise a revoked order is reported as Failed (the gateway has a record without a body) or skipped (no record), so the gateway never stores a revoked record without a certificate. From f806c4deb64c96df79fd8e86b75e53f42ca47cf9 Mon Sep 17 00:00:00 2001 From: spbsoluble <1661003+spbsoluble@users.noreply.github.com> Date: Sat, 14 Nov 2026 12:56:06 -0800 Subject: [PATCH 02/11] fix(dcv): look each SSL.com-candidate domain up once per V2 sync pass FindSslComDomainAsync called GET /domains for every pending domain on every DCV attempt, so a pass over many orders under one domain repeated the same lookup. A per-pass cache (one per sync pass, one per Enroll/GetSingleRecord DCV call) keeps found rows and "no row"; failed lookups aren't cached and fall back to emSign as before. Only DomainId/validatedBy come from the cached row; DCV state is still read fresh per order. Sync processes rows sequentially, so a plain dictionary. --- .../V2SslComDomainDcvPluginTests.cs | 106 ++++++++++++++++++ CERTInext/CERTInextCAPlugin.cs | 45 ++++++-- CHANGELOG.md | 1 + docsource/architecture.md | 2 +- 4 files changed, 143 insertions(+), 11 deletions(-) diff --git a/CERTInext.Tests/V2SslComDomainDcvPluginTests.cs b/CERTInext.Tests/V2SslComDomainDcvPluginTests.cs index 33aa236..5ac2f47 100644 --- a/CERTInext.Tests/V2SslComDomainDcvPluginTests.cs +++ b/CERTInext.Tests/V2SslComDomainDcvPluginTests.cs @@ -389,5 +389,111 @@ public async Task Ucc_SslComSanUnderReview_EmsignSanStillVerified_OrderStaysPend result.Status.Should().Be((int)EndEntityStatus.EXTERNALVALIDATION); validator.CleanedUpKeys.Should().HaveCount(2, "both staged records are cleaned up"); } + + // --------------------------------------------------------------------------- + // GET /domains lookups are cached per sync pass: many pending orders share a domain. + // --------------------------------------------------------------------------- + + private static async IAsyncEnumerable Rows(params OrderReportEntryV2[] rows) + { + foreach (var r in rows) yield return r; + await Task.CompletedTask; + } + + private static OrderReportEntryV2 PendingRow(string orderNumber, string domain) => + new OrderReportEntryV2 + { + OrderNumber = orderNumber, OrderStatus = "Order Accepted", CertificateStatus = "Pending for Approver", + DomainName = domain, OrderDate = DateTime.UtcNow.AddMinutes(-30).ToString("o") + }; + + /// + /// Loose mock for a sync pass over pending SSL orders. Each order's own DCV fails fast at + /// GET /domains/{id}/dcv (SSL.com row) or GET /dcv (emSign), leaving it pending: these tests + /// count lookups, not DCV outcomes. + /// + private static Mock NewSyncMock(params (string id, string domain)[] orders) + { + var mock = new Mock(); + mock.Setup(c => c.ListOrdersV2Async(It.IsAny(), It.IsAny(), It.IsAny(), It.IsAny())) + .Returns(() => Rows(orders.Select(o => PendingRow(o.id, o.domain)).ToArray())); + foreach (var (id, domain) in orders) + mock.Setup(c => c.ResolveAndTrackOrderV2WithFamilyAsync(id, It.IsAny())) + .ReturnsAsync((Constants.ApiV2.FamilySsl, new V2OrderStatusResponse { OrderId = id, Status = "pending-dcv", Domain = domain })); + mock.Setup(c => c.GetDomainDcvV2Async(It.IsAny(), It.IsAny())) + .ThrowsAsync(new Exception("CERTInext V2 API error during 'V2 get domain DCV'. HTTP 502.")); + mock.Setup(c => c.GetDcvV2Async(It.IsAny(), It.IsAny(), It.IsAny())) + .ThrowsAsync(new Exception("simulated GetDcv failure")); + return mock; + } + + private static CERTInextCAPlugin BuildSyncPlugin(ICERTInextClient client) => + new CERTInextCAPlugin(client, new FakeDomainValidatorFactory(new FakeDomainValidator()), new CERTInextConfig + { + UseV2Api = true, ApiUrl = "https://v2.certinext.io", OAuthClientId = "c", OAuthClientSecret = "s", + DcvEnabled = true, DcvTimeoutMinutes = 1, DcvPropagationDelaySeconds = 1, + DcvSyncMaxOrderAgeHours = 0, DcvSyncMaxPerPass = 0 + }); + + private static Task SyncOnce(CERTInextCAPlugin plugin) => + plugin.Synchronize(new System.Collections.Concurrent.BlockingCollection(100), null, true, + CancellationToken.None); + + [Fact] + public async Task Sync_TwoOrdersSameDomain_LooksDomainUpOnce_ReadsDcvStateForEach() + { + var mock = NewSyncMock(("ord_a", Domain), ("ord_b", Domain.ToUpperInvariant())); + mock.Setup(c => c.FindDomainV2Async(It.IsAny(), It.IsAny())).ReturnsAsync(SslComRow()); + + await SyncOnce(BuildSyncPlugin(mock.Object)); + + mock.Verify(c => c.FindDomainV2Async(It.IsAny(), It.IsAny()), Times.Once, + "the second order's domain (different case) is answered from the pass cache"); + mock.Verify(c => c.GetDomainDcvV2Async(DomainId, It.IsAny()), Times.Exactly(2), + "the cached row supplies only the domain id; each order still reads SSL.com's current DCV state"); + } + + [Fact] + public async Task Sync_NoDomainRow_IsCachedToo() + { + var mock = NewSyncMock(("ord_a", Domain), ("ord_b", Domain)); + mock.Setup(c => c.FindDomainV2Async(Domain, It.IsAny())).ReturnsAsync((V2DomainRecord)null); + + await SyncOnce(BuildSyncPlugin(mock.Object)); + + mock.Verify(c => c.FindDomainV2Async(Domain, It.IsAny()), Times.Once); + mock.Verify(c => c.GetDcvV2Async(It.IsAny(), It.IsAny(), It.IsAny()), Times.Exactly(2), + "both orders take the emSign flow"); + } + + [Fact] + public async Task Sync_FailedLookup_IsNotCached_NextOrderTriesAgain() + { + var mock = NewSyncMock(("ord_a", Domain), ("ord_b", Domain)); + mock.SetupSequence(c => c.FindDomainV2Async(Domain, It.IsAny())) + .ThrowsAsync(new Exception("CERTInext V2 API error during 'V2 find domain'. HTTP 500.")) + .ReturnsAsync(SslComRow()); + + await SyncOnce(BuildSyncPlugin(mock.Object)); + + mock.Verify(c => c.FindDomainV2Async(Domain, It.IsAny()), Times.Exactly(2)); + mock.Verify(c => c.GetDcvV2Async("ord_a", It.IsAny(), It.IsAny()), Times.Once, + "the failed lookup falls back to the emSign flow, as before"); + mock.Verify(c => c.GetDomainDcvV2Async(DomainId, It.IsAny()), Times.Once, + "the retried lookup found the SSL.com row for the second order"); + } + + [Fact] + public async Task Sync_NewPass_LooksDomainUpAgain() + { + var mock = NewSyncMock(("ord_a", Domain)); + mock.Setup(c => c.FindDomainV2Async(Domain, It.IsAny())).ReturnsAsync(SslComRow()); + var plugin = BuildSyncPlugin(mock.Object); + + await SyncOnce(plugin); + await SyncOnce(plugin); + + mock.Verify(c => c.FindDomainV2Async(Domain, It.IsAny()), Times.Exactly(2)); + } } } diff --git a/CERTInext/CERTInextCAPlugin.cs b/CERTInext/CERTInextCAPlugin.cs index 94a8ed8..8e85395 100644 --- a/CERTInext/CERTInextCAPlugin.cs +++ b/CERTInext/CERTInextCAPlugin.cs @@ -3526,6 +3526,8 @@ private async Task SynchronizeV2Async( int emittedFailedFromBodylessRevoked = 0, skippedBodylessRevoked = 0; #if SUPPORTS_DCV + // SSL.com domain lookups (GET /domains) for this pass: many orders share a domain. + var domainLookups = NewDomainLookupCache(); bool dcvOperational = _config.DcvEnabled && _domainValidatorFactory != null; int ageWindowHours = _config.DcvSyncMaxOrderAgeHours; int perPassCap = _config.DcvSyncMaxPerPass; @@ -3694,7 +3696,7 @@ private async Task SynchronizeV2Async( { bool dcvDone = await PerformDcvV2IfNeededAsync( row.OrderNumber, domain, resolvedFamily, dcvCts.Token, - trackedStatus?.Verifications?.Domain?.Domains); + trackedStatus?.Verifications?.Domain?.Domains, domainLookups); if (dcvDone) { trackedStatus = await _client.ResolveAndTrackOrderV2Async(row.OrderNumber, cancelToken); @@ -5455,7 +5457,8 @@ private async Task PerformDcvV2IfNeededAsync( string domain, string productFamilySlug, CancellationToken ct, - IReadOnlyList domainEntries = null) + IReadOnlyList domainEntries = null, + Dictionary domainLookups = null) { if (_domainValidatorFactory == null || !_config.DcvEnabled) { @@ -5498,11 +5501,14 @@ private async Task PerformDcvV2IfNeededAsync( return false; } + // Enroll and GetSingleRecord get a cache for this one call; a sync pass passes its own. + domainLookups ??= NewDomainLookupCache(); + try { return multiDomainMode - ? await PerformDcvV2MultiDomainAsync(orderId, domainEntries, productFamilySlug, ct) - : await PerformDcvV2SingleDomainAsync(orderId, domain, productFamilySlug, ct); + ? await PerformDcvV2MultiDomainAsync(orderId, domainEntries, productFamilySlug, ct, domainLookups) + : await PerformDcvV2SingleDomainAsync(orderId, domain, productFamilySlug, ct, domainLookups); } finally { @@ -5538,13 +5544,14 @@ private async Task PerformDcvV2SingleDomainAsync( string orderId, string domain, string productFamilySlug, - CancellationToken ct) + CancellationToken ct, + Dictionary domainLookups) { _logger.LogInformation( "V2 DCV starting for order {OrderId}, domain {Domain}.", orderId, LogSanitizer.Strip(domain)); // A domain SSL.com validates takes the domain-level flow with SSL.com's own record. - var sslComDomain = await FindSslComDomainAsync(orderId, domain, ct); + var sslComDomain = await FindSslComDomainAsync(orderId, domain, ct, domainLookups); if (sslComDomain != null) return await PerformDcvV2SslComSingleDomainAsync(orderId, domain, sslComDomain, productFamilySlug, ct); @@ -5745,7 +5752,8 @@ private async Task PerformDcvV2MultiDomainAsync( string orderId, IReadOnlyList domainEntries, string productFamilySlug, - CancellationToken ct) + CancellationToken ct, + Dictionary domainLookups) { var pendingDomains = domainEntries .Where(e => !string.IsNullOrWhiteSpace(e?.Domain) @@ -5807,7 +5815,7 @@ async Task CleanupStagedAsync() { ct.ThrowIfCancellationRequested(); - var sslComDomain = await FindSslComDomainAsync(orderId, d, ct); + var sslComDomain = await FindSslComDomainAsync(orderId, d, ct, domainLookups); if (sslComDomain != null) { var (plan, skipReason) = await PrepareSslComDcvAsync(orderId, d, sslComDomain, ct); @@ -6145,16 +6153,33 @@ private sealed class SslComDcvPlan public Keyfactor.AnyGateway.Extensions.IDomainValidator Validator { get; init; } } + /// + /// Per-pass cache for : domain (case-insensitive) to the + /// account's GET /domains row, or null for "no row". One per sync pass and one per + /// Enroll/GetSingleRecord DCV attempt. Not thread-safe; sync processes rows one at a time. + /// + internal static Dictionary NewDomainLookupCache() => + new Dictionary(StringComparer.OrdinalIgnoreCase); + /// /// Returns the account's domain row when SSL.com validates , else null. /// A failed lookup also returns null, so the order takes the emSign path it took before the /// SSL.com path existed, with a warning; cancellation propagates. + /// Found rows and "no row" are cached in , so a pass looks each + /// domain up once; only DomainId and validatedBy are read from a cached row, and + /// the DCV state comes from a fresh GET /domains/{id}/dcv. Failures aren't cached, so the + /// next order on the same domain tries again. /// - private async Task FindSslComDomainAsync(string orderId, string domain, CancellationToken ct) + private async Task FindSslComDomainAsync( + string orderId, string domain, CancellationToken ct, Dictionary domainLookups) { try { - var row = await _client.FindDomainV2Async(domain, ct); + if (!domainLookups.TryGetValue(domain, out var row)) + { + row = await _client.FindDomainV2Async(domain, ct); + domainLookups[domain] = row; + } if (row?.IsValidatedBySslCom != true) return null; _logger.LogInformation( diff --git a/CHANGELOG.md b/CHANGELOG.md index 24a655a..3fbad8c 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -33,6 +33,7 @@ - fix(enroll): V2 order and CSR submissions are never auto-retried after a timeout, which could create duplicate orders (V1 since 1.0.1). - fix(sync): A V2 order that `/reports/orders` lists but Track Order finds in no product family (seen for every `On Hold | Setup Pending` row) is skipped with one Information line and counted as `UntrackableListedOrders` in the sync summary. It used to log an error with a stack trace and count toward the sync's 25% error-rate abort. - fix(sync): The V2 sync summary lists every `orderStatus | certificateStatus` pair from `/reports/orders` that the plugin didn't recognize, with counts (`UnmappedReportStatuses=[...]`), at Information. CERTInext doesn't document these values, so new ones now show up in ordinary logs. +- fix(dcv): V2 DCV looks each domain up (`GET /domains`) once per sync pass, and once per `Enroll` or single-record call, instead of once per pending order and SAN. Found rows and "no row" are reused; a failed lookup is not, so the next order on that domain tries again. - fix(sync): A V2 `/reports/orders` row that reads `Order Fulfilled | Pending for Approver` is resolved through Track Order, which returns `issued`, so the certificate is downloaded. It used to be reported as pending and never downloaded. Other disagreeing pairs, such as `Order Accepted | Certificate Revoked`, keep their mapping, because the certificate status is correct for them. - fix(v2): A V2 OAuth2 token request that gets no HTTP response (a dropped connection or other transport error) is retried twice, after 1 s and 3 s, so one network blip no longer fails an enrollment, a sync or a connector save. HTTP errors (400/401/403) are not retried, and order creates are still never retried. Token failures and other V2 calls with no response now log the transport detail (`TransportDetail=`: RestSharp's response status and the exception types and messages, with credentials removed) and include a short form in the error, instead of only `HttpStatus=0`. - fix(sync): The V2 sync also holds back pending and issued orders created in the last 120 s (`SyncRecentOrderGraceSeconds`, `0` disables), so an in-flight enrollment no longer fails with a duplicate key (V1 since 1.0.1). diff --git a/docsource/architecture.md b/docsource/architecture.md index 4a39580..df72ec4 100644 --- a/docsource/architecture.md +++ b/docsource/architecture.md @@ -298,7 +298,7 @@ For an order that lists per-domain verification state (a multi-domain order, for ##### SSL.com-validated domains (V2) -Before it requests a challenge for a pending domain, the V2 flow looks the domain up (`GET /domains?search={domain}&exactMatch=true`). A domain whose row says `validatedBy: SSLCOM` uses the domain-level DCV endpoints instead of the order-level ones: +Before it requests a challenge for a pending domain, the V2 flow looks the domain up (`GET /domains?search={domain}&exactMatch=true`). Each sync pass, and each `Enroll` or single-record DCV attempt, looks a domain up once and reuses the answer, including "no row", for every other order on that domain. A failed lookup isn't reused, so the next order on that domain tries again. A domain whose row says `validatedBy: SSLCOM` uses the domain-level DCV endpoints instead of the order-level ones: 1. `GET /domains/{domainId}/dcv` returns SSL.com's record. If SSL.com reports the domain `VALIDATED`, step 2 is skipped. 2. The plugin picks a `dns-txt` option, preferring the selected one, then one for exactly this name. It publishes that `recordName` and `recordValue` through the DNS provider plugin and ignores `DcvTxtRecordTemplate`. `dns-cname` and `http-url` options are not used, because the DNS provider interface (`IAnyCAPlugin` 3.3) can only publish TXT records. From 0ab574da58290b0715632584a7cf27b4e30079e0 Mon Sep 17 00:00:00 2001 From: spbsoluble <1661003+spbsoluble@users.noreply.github.com> Date: Sat, 14 Nov 2026 13:05:13 -0800 Subject: [PATCH 03/11] fix(enroll): bound the in-call pickup wait by a deadline from Enroll entry Command fails the Keyfactor-Enroll workflow step at its global Workflow Step Run Timeout (Workflow.General.Timeout, 60 s by default; the step has no timeout of its own). The pickup budget (5 s + PickupRetries x PickupDelay, capped at 75 s) was counted from the start of the pickup, so the create time came on top: on the lab a new DV order and a reissue (26 s) both reached Command's 60 s, which recorded a failure while the order went on at CERTInext. New setting EnrollmentCallBudgetSeconds (default 50, 0 disables, clamped to 90 under the 100 s HttpClient timeout). Enroll starts an EnrollmentDeadline, carried in an AsyncLocal to the V1 new/renew and V2 pickups. They shorten waits to keep a 3 s poll margin, skip the delay after the last poll, and stop with one Information line when no poll fits. In-flight calls are never cut short; PickupRetries=0 is unchanged; inline DCV is not bounded (documented as a known limitation). --- CERTInext.Tests/EnrollmentDeadlineTests.cs | 326 +++++++++++++++++++++ CERTInext/CERTInextCAPlugin.cs | 103 +++++-- CERTInext/CERTInextCAPluginConfig.cs | 38 ++- CERTInext/Constants.cs | 21 ++ CERTInext/EnrollmentDeadline.cs | 57 ++++ CHANGELOG.md | 3 +- docsource/architecture.md | 2 +- docsource/configuration.md | 13 + docsource/overview.md | 2 +- integration-manifest.json | 9 +- 10 files changed, 550 insertions(+), 24 deletions(-) create mode 100644 CERTInext.Tests/EnrollmentDeadlineTests.cs create mode 100644 CERTInext/EnrollmentDeadline.cs diff --git a/CERTInext.Tests/EnrollmentDeadlineTests.cs b/CERTInext.Tests/EnrollmentDeadlineTests.cs new file mode 100644 index 0000000..aa4dd0a --- /dev/null +++ b/CERTInext.Tests/EnrollmentDeadlineTests.cs @@ -0,0 +1,326 @@ +// Copyright 2026 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 System; +using System.Collections.Generic; +using System.Linq; +using System.Threading; +using System.Threading.Tasks; +using FluentAssertions; +using Keyfactor.AnyGateway.Extensions; +using Keyfactor.Extensions.CAPlugin.CERTInext.API; +using Keyfactor.Extensions.CAPlugin.CERTInext.API.V2; +using Keyfactor.Extensions.CAPlugin.CERTInext.Client; +using Keyfactor.PKI.Enums.EJBCA; +using Microsoft.Extensions.Logging; +using Moq; +using Xunit; + +namespace Keyfactor.Extensions.CAPlugin.CERTInext.Tests +{ + /// + /// EnrollmentCallBudgetSeconds: the in-call pickup wait is bounded by a deadline measured from + /// Enroll() entry, so time spent creating or reissuing the order counts against it and the call + /// returns before Command's workflow step timeout (60 s by default). Driven on a manual clock: the + /// plugin's pickup waits advance it instead of sleeping, and each CA call advances it by its latency. + /// + [Collection(LoggingStateCollection.Name)] + public class EnrollmentDeadlineTests + { + private const string OrderId = "ord_deadline_001"; + private static readonly TimeSpan PollLatency = TimeSpan.FromSeconds(0.5); + + private sealed class ManualClock : TimeProvider + { + private long _ticks; + public override long TimestampFrequency => TimeSpan.TicksPerSecond; + public override long GetTimestamp() => Interlocked.Read(ref _ticks); + public void Advance(TimeSpan by) => Interlocked.Add(ref _ticks, by.Ticks); + } + + private sealed class Harness + { + public ManualClock Clock { get; } = new ManualClock(); + public List Waits { get; } = new List(); + + public CERTInextCAPlugin Wire(CERTInextCAPlugin plugin) + { + plugin.Clock = Clock; + plugin.PickupDelayAsync = (d, ct) => + { + Waits.Add(d); + Clock.Advance(d); + return Task.CompletedTask; + }; + return plugin; + } + } + + // --------------------------------------------------------------------------- + // TryGetWait + // --------------------------------------------------------------------------- + + [Fact] + public void TryGetWait_NoDeadline_KeepsDesiredWait() + { + EnrollmentDeadline.TryGetWait(null, TimeSpan.FromSeconds(10), out var wait).Should().BeTrue(); + wait.Should().Be(TimeSpan.FromSeconds(10)); + } + + [Theory] + [InlineData(0, 10, true, 10)] // plenty left + [InlineData(42, 10, true, 5)] // 8 s left: wait shortened to leave the 3 s poll margin + [InlineData(47, 10, false, 0)] // 3 s left: no room for a poll + [InlineData(49, 5, false, 0)] + public void TryGetWait_ShortensOrRefuses_ByRemainingBudget(int elapsed, int desired, bool expectOk, int expectedWait) + { + var clock = new ManualClock(); + var deadline = new EnrollmentDeadline(clock, TimeSpan.FromSeconds(50)); + clock.Advance(TimeSpan.FromSeconds(elapsed)); + + EnrollmentDeadline.TryGetWait(deadline, TimeSpan.FromSeconds(desired), out var wait).Should().Be(expectOk); + if (expectOk) + wait.Should().Be(TimeSpan.FromSeconds(expectedWait)); + } + + [Theory] + [InlineData(50, 50)] + [InlineData(0, 0)] + [InlineData(-5, 50)] + [InlineData(120, 90)] + [InlineData(75, 75)] + public void EffectiveBudget_ZeroDisables_NegativeDefaults_ClampedBelowHttpTimeout(int configured, int expected) + { + new CERTInextConfig { EnrollmentCallBudgetSeconds = configured } + .GetEffectiveEnrollmentCallBudgetSeconds().Should().Be(expected); + } + + [Fact] + public void DefaultConfig_HasFiftySecondBudget() + { + new CERTInextConfig().GetEffectiveEnrollmentCallBudgetSeconds().Should().Be(50); + } + + // --------------------------------------------------------------------------- + // V2 + // --------------------------------------------------------------------------- + + private static CERTInextConfig V2Config(int retries = 5, int delay = 10, int? budget = null) + { + var config = new CERTInextConfig + { + UseV2Api = true, ApiUrl = "https://v2.certinext.io", OAuthClientId = "id", OAuthClientSecret = "s", + AccountNumber = "12345", RequestorName = "Test User", RequestorEmail = "test@example.com", + SignerPlace = "New York", PickupRetries = retries, PickupDelayInSeconds = delay + }; + if (budget.HasValue) + config.EnrollmentCallBudgetSeconds = budget.Value; + return config; + } + + /// + /// A V2 DV order that stays pending: the create takes , and every + /// Track Order call takes . + /// + private static Mock PendingV2Order(Harness h, TimeSpan createLatency) + { + var mock = new Mock(); + mock.Setup(c => c.GetProductDetailsV2Async(It.IsAny())) + .ReturnsAsync(new List { new ProductDetail { ProductCode = "842", ProductTypeId = "13", Active = true } }); + mock.Setup(c => c.PlaceOrderV2Async(It.IsAny(), It.IsAny(), It.IsAny(), It.IsAny())) + .Callback(() => h.Clock.Advance(createLatency)) + .ReturnsAsync(new V2CreateOrderResponse { OrderId = OrderId, Status = "pending-dcv" }); + mock.Setup(c => c.TrackOrderV2Async(It.IsAny(), OrderId, It.IsAny())) + .Callback(() => h.Clock.Advance(PollLatency)) + .ReturnsAsync(new V2OrderStatusResponse { OrderId = OrderId, Status = "pending-dcv" }); + return mock; + } + + private static Task EnrollV2(CERTInextCAPlugin plugin) => + plugin.Enroll( + MockCertificateData.FakeCsrPem, "CN=example.com", + new Dictionary { ["dns"] = new[] { "example.com" } }, + new EnrollmentProductInfo + { + ProductID = "DV SSL", + ProductParameters = new Dictionary(StringComparer.OrdinalIgnoreCase) + { + ["ProductCode"] = "842", ["ProductFamily"] = "ssl", ["ProductVariant"] = "dv", + ["DomainName"] = "example.com" + } + }, + RequestFormat.PKCS10, EnrollmentType.New); + + private static int PickupPolls(Mock mock, int callsBeforePickup) => + mock.Invocations.Count(i => i.Method.Name == nameof(ICERTInextClient.TrackOrderV2Async)) - callsBeforePickup; + + [Fact] + public async Task V2_CreateUsedMostOfBudget_SkipsPickup_ReturnsPendingInsideBudget() + { + using var capture = new PluginLogCapture(); + var h = new Harness(); + var mock = PendingV2Order(h, TimeSpan.FromSeconds(47)); + var plugin = h.Wire(new CERTInextCAPlugin(mock.Object, V2Config())); + + var result = await EnrollV2(plugin); + + result.Status.Should().Be((int)EndEntityStatus.EXTERNALVALIDATION); + result.CARequestID.Should().Be(OrderId); + h.Waits.Should().BeEmpty("47 s create + the post-create status check leave no room for a poll"); + h.Clock.GetElapsedTime(0).Should().BeLessThan(TimeSpan.FromSeconds(50)); + capture.Lines(LogLevel.Information, "stopped early").Should().ContainSingle() + .Which.Should().Contain("of the 50 s EnrollmentCallBudgetSeconds").And.Contain("0 of 5 attempt(s) ran"); + } + + [Fact] + public async Task V2_SlowReissueLikeCreate_26s_PickupFitsTheRemainingBudget() + { + // The live reissue took 25.8 s before the pickup started. The default pickup (5 s + 5 x 10 s) + // then ran to ~60 s after Enroll started; now it is cut to what's left of the 50 s. + using var capture = new PluginLogCapture(); + var h = new Harness(); + var mock = PendingV2Order(h, TimeSpan.FromSeconds(26)); + var plugin = h.Wire(new CERTInextCAPlugin(mock.Object, V2Config())); + int trackBeforePickup = 1; // the post-create status check + + var result = await EnrollV2(plugin); + + result.Status.Should().Be((int)EndEntityStatus.EXTERNALVALIDATION); + // 26.5 s used: wait 5, poll (0.5), wait 10, poll (at 42.5 s), then 4.5 s (shortened from 10, keeping + // the 3 s poll margin) and a last poll. + h.Waits.Should().Equal(TimeSpan.FromSeconds(5), TimeSpan.FromSeconds(10), TimeSpan.FromSeconds(4.5)); + PickupPolls(mock, trackBeforePickup).Should().Be(3); + h.Clock.GetElapsedTime(0).Should().BeLessThanOrEqualTo(TimeSpan.FromSeconds(50)); + capture.Lines(LogLevel.Information, "stopped early").Should().ContainSingle() + .Which.Should().Contain("3 of 5 attempt(s) ran"); + } + + [Fact] + public async Task V2_FastCreate_DefaultPickupFitsUntilTheBudgetIsReached() + { + var h = new Harness(); + var mock = PendingV2Order(h, TimeSpan.FromSeconds(1)); + var plugin = h.Wire(new CERTInextCAPlugin(mock.Object, V2Config())); + + await EnrollV2(plugin); + + h.Clock.GetElapsedTime(0).Should().BeLessThanOrEqualTo(TimeSpan.FromSeconds(50)); + h.Waits.Sum(w => w.TotalSeconds).Should().BeGreaterThan(40, "a fast create leaves most of the budget for polling"); + } + + [Fact] + public async Task V2_PickupRetriesZero_Unchanged_NoWaitNoPoll() + { + using var capture = new PluginLogCapture(); + var h = new Harness(); + var mock = PendingV2Order(h, TimeSpan.FromSeconds(1)); + var plugin = h.Wire(new CERTInextCAPlugin(mock.Object, V2Config(retries: 0))); + + var result = await EnrollV2(plugin); + + result.Status.Should().Be((int)EndEntityStatus.EXTERNALVALIDATION); + h.Waits.Should().BeEmpty(); + PickupPolls(mock, 1).Should().Be(0); + capture.Lines(LogLevel.Information, "PickupRetries<=0").Should().ContainSingle(); + capture.Lines(LogLevel.Information, "stopped early").Should().BeEmpty(); + } + + [Fact] + public async Task V2_BudgetZero_NoDeadline_KeepsFullCadenceIncludingTrailingDelay() + { + var h = new Harness(); + var mock = PendingV2Order(h, TimeSpan.FromSeconds(30)); + var plugin = h.Wire(new CERTInextCAPlugin(mock.Object, V2Config(retries: 3, delay: 10, budget: 0))); + + await EnrollV2(plugin); + + h.Waits.Should().Equal( + TimeSpan.FromSeconds(5), TimeSpan.FromSeconds(10), TimeSpan.FromSeconds(10), TimeSpan.FromSeconds(10)); + PickupPolls(mock, 1).Should().Be(3); + } + + [Fact] + public async Task V2_NoDelayAfterLastPoll_UnderDeadline() + { + var h = new Harness(); + var mock = PendingV2Order(h, TimeSpan.FromSeconds(1)); + var plugin = h.Wire(new CERTInextCAPlugin(mock.Object, V2Config(retries: 2, delay: 10))); + + await EnrollV2(plugin); + + h.Waits.Should().Equal(TimeSpan.FromSeconds(5), TimeSpan.FromSeconds(10)); + PickupPolls(mock, 1).Should().Be(2); + } + + // --------------------------------------------------------------------------- + // V1 (new enroll and renew both use PickUpEnrolledCertificateAsync) + // --------------------------------------------------------------------------- + + private static EnrollmentProductInfo V1ProductInfo(Dictionary extras = null) + { + var parameters = new Dictionary(StringComparer.OrdinalIgnoreCase) + { + ["ProfileId"] = MockCertificateData.ProfileIdTls + }; + foreach (var kv in extras ?? new Dictionary()) + parameters[kv.Key] = kv.Value; + return new EnrollmentProductInfo { ProductID = MockCertificateData.ProfileIdTls, ProductParameters = parameters }; + } + + [Fact] + public async Task V1_NewEnroll_SlowOrder_PickupHonoursDeadline() + { + using var capture = new PluginLogCapture(); + var h = new Harness(); + var mock = new Mock(MockBehavior.Strict); + mock.Setup(c => c.EnrollCertificateAsync(It.IsAny(), It.IsAny())) + .Callback(() => h.Clock.Advance(TimeSpan.FromSeconds(40))) + .ReturnsAsync(MockCertificateData.PendingEnrollResponse()); + mock.Setup(c => c.GetCertificateAsync(It.IsAny(), It.IsAny())) + .Callback(() => h.Clock.Advance(PollLatency)) + .ReturnsAsync(MockCertificateData.PendingCertRecord()); + var plugin = h.Wire(new CERTInextCAPlugin(mock.Object, new CERTInextConfig { PickupRetries = 5, PickupDelayInSeconds = 10 })); + + var result = await plugin.Enroll(MockCertificateData.FakeCsrPem, "CN=test.example.com", null, + V1ProductInfo(), RequestFormat.PKCS10, EnrollmentType.New); + + result.Status.Should().Be((int)EndEntityStatus.EXTERNALVALIDATION); + // 10 s left: wait 5, poll (0.5), then 1.5 s (shortened), a last poll, and stop. + h.Waits.Should().Equal(TimeSpan.FromSeconds(5), TimeSpan.FromSeconds(1.5)); + mock.Verify(c => c.GetCertificateAsync(It.IsAny(), It.IsAny()), Times.Exactly(2)); + h.Clock.GetElapsedTime(0).Should().BeLessThanOrEqualTo(TimeSpan.FromSeconds(50)); + capture.Lines(LogLevel.Information, "stopped early").Should().ContainSingle(); + } + + [Fact] + public async Task V1_Renew_SlowRenewal_SkipsPickupWhenNoPollFits() + { + const string prior = "ORD-PRIOR-001"; + var h = new Harness(); + var reader = new Mock(); + reader.Setup(r => r.GetRequestIDBySerialNumber(It.IsAny())).ReturnsAsync(prior); + reader.Setup(r => r.GetExpirationDateByRequestId(prior)).Returns(DateTime.UtcNow.AddDays(30)); + var mock = new Mock(MockBehavior.Strict); + mock.Setup(c => c.RenewCertificateAsync(prior, It.IsAny(), It.IsAny())) + .Callback(() => h.Clock.Advance(TimeSpan.FromSeconds(48))) + .ReturnsAsync(MockCertificateData.PendingEnrollResponse("ORD-RENEW-002")); + var plugin = h.Wire(new CERTInextCAPlugin(mock.Object, reader.Object, + new CERTInextConfig { PickupRetries = 5, PickupDelayInSeconds = 10, DcvEnabled = false })); + + var result = await plugin.Enroll(MockCertificateData.FakeCsrPem, "CN=renew.example.com", + new Dictionary { ["dns"] = new[] { "renew.example.com" } }, + V1ProductInfo(new Dictionary { ["PriorCertSN"] = "AABB", ["RenewalWindowDays"] = "90" }), + RequestFormat.PKCS10, EnrollmentType.RenewOrReissue); + + result.CARequestID.Should().Be("ORD-RENEW-002"); + result.Status.Should().Be((int)EndEntityStatus.EXTERNALVALIDATION); + h.Waits.Should().BeEmpty(); + mock.Verify(c => c.GetCertificateAsync(It.IsAny(), It.IsAny()), Times.Never, + "the strict mock would also throw: no poll fits in the 2 s left"); + } + } +} diff --git a/CERTInext/CERTInextCAPlugin.cs b/CERTInext/CERTInextCAPlugin.cs index 8e85395..02e1279 100644 --- a/CERTInext/CERTInextCAPlugin.cs +++ b/CERTInext/CERTInextCAPlugin.cs @@ -87,6 +87,16 @@ public class CERTInextCAPlugin : IAnyCAPlugin, IDisposable // to stage TXT records for the same order. The value byte is unused; this is a set. private readonly ConcurrentDictionary _dcvInFlight = new(); + // The EnrollmentCallBudgetSeconds deadline of the Enroll() call on this async flow, read by + // both pickup methods. Async-local so concurrent enrollments each see their own, and so the + // V1 new/renew and V2 pickup call sites need no extra parameters. Null outside Enroll() and + // when the budget is 0. + private readonly AsyncLocal _enrollDeadline = new(); + + // Test seams for the enrollment deadline: the clock it is measured on, and the pickup's waits. + internal TimeProvider Clock { get; set; } = TimeProvider.System; + internal Func PickupDelayAsync { get; set; } = Task.Delay; + // --------------------------------------------------------------------------- // Constructors // --------------------------------------------------------------------------- @@ -951,6 +961,12 @@ public async Task Enroll( { _logger.MethodEntry(LogLevel.Debug); + // Start the deadline first, so everything before the pickup counts against it. + int budgetSeconds = _config.GetEffectiveEnrollmentCallBudgetSeconds(); + _enrollDeadline.Value = budgetSeconds > 0 + ? new EnrollmentDeadline(Clock, TimeSpan.FromSeconds(budgetSeconds)) + : null; + var ep = new EnrollmentParams(productInfo); // SOX / SOC2 CC7.3: log the enrollment attempt with full identifying context @@ -6759,14 +6775,22 @@ private async Task PickUpEnrolledCertificateAsync( Constants.Pickup.InitialDelaySeconds + retries * delaySeconds, Constants.Pickup.InitialDelaySeconds); int pollErrors = 0; + int attemptsRun = 0; + var deadline = _enrollDeadline.Value; + bool stoppedByDeadline = false; try { // Small static delay before the first poll — mirrors the Sectigo connector's // attempt to let a fast order finish issuing before we start polling at all. - await Task.Delay(TimeSpan.FromSeconds(Constants.Pickup.InitialDelaySeconds), ct); + // The enrollment deadline can shorten it, or skip the pickup when no poll fits. + stoppedByDeadline = !EnrollmentDeadline.TryGetWait( + deadline, TimeSpan.FromSeconds(Constants.Pickup.InitialDelaySeconds), out TimeSpan initialWait); + if (!stoppedByDeadline) + await PickupDelayAsync(initialWait, ct); - for (int attempt = 1; attempt <= retries; attempt++) + for (int attempt = 1; attempt <= retries && !stoppedByDeadline; attempt++) { + attemptsRun = attempt; try { var cert = await _client.GetCertificateAsync(orderNumber, ct); @@ -6839,26 +6863,35 @@ private async Task PickUpEnrolledCertificateAsync( } // Delay after every attempt (including the last), matching the Sectigo - // connector's pickup cadence so the max-occupancy ceiling is identical. - await Task.Delay(TimeSpan.FromSeconds(delaySeconds), ct); + // connector's pickup cadence so the max-occupancy ceiling is identical. Under an + // enrollment deadline the delay after the last attempt is skipped (no poll follows + // it), and the others are shortened or end the pickup when no poll fits. + if (deadline != null && attempt == retries) + break; + stoppedByDeadline = !EnrollmentDeadline.TryGetWait( + deadline, TimeSpan.FromSeconds(delaySeconds), out TimeSpan wait); + if (!stoppedByDeadline) + await PickupDelayAsync(wait, ct); } // SOC1 accuracy: don't attribute non-completion to "OV/EV async by design" when the // real cause was every poll erroring (e.g. a CA-side TrackOrder outage). Distinguish // the two so the log reflects what actually happened. - if (pollErrors == retries) + if (attemptsRun > 0 && pollErrors == attemptsRun) _logger.LogWarning( "Synchronous pickup exhausted {Retries} attempts for order {OrderNumber} — ALL polls " + "errored (see preceding warnings). Returning pending result; the next synchronization " + "will re-attempt retrieval.", - retries, orderNumber); - else + attemptsRun, orderNumber); + if (stoppedByDeadline) + LogPickupStoppedByDeadline(orderNumber, deadline, attemptsRun, retries); + else if (pollErrors != attemptsRun) _logger.LogInformation( "Synchronous pickup did not complete within {Retries} attempts for order {OrderNumber} " + "({Errors} poll error(s); remainder still pending). Returning pending result; the " + "certificate will be imported by the next synchronization. CERTInext issues OV/EV " + "asynchronously by design.", - retries, orderNumber, pollErrors); + attemptsRun, orderNumber, pollErrors); pendingResult.StatusMessage = $"{pendingResult.StatusMessage} The certificate was not issued within the enrollment-pickup " + "window; it will be imported by a later synchronization."; @@ -6873,6 +6906,20 @@ private async Task PickUpEnrolledCertificateAsync( return pendingResult; } + /// + /// The one Information line for a pickup the enrollment deadline ended before its configured + /// attempts ran out: elapsed time since Enroll() started, the budget, and why. + /// + private void LogPickupStoppedByDeadline(string orderId, EnrollmentDeadline deadline, int attemptsRun, int retries) + { + _logger.LogInformation( + "Synchronous pickup for order {OrderId} stopped early: {Elapsed:F1} s of the {Budget} s " + + "EnrollmentCallBudgetSeconds had passed since Enroll started, leaving too little time for another " + + "poll ({Attempts} of {Retries} attempt(s) ran). Returning pending result so the enrollment returns " + + "before Command's workflow step timeout; the certificate will be imported by the next synchronization.", + orderId, deadline.Elapsed.TotalSeconds, (int)deadline.Budget.TotalSeconds, attemptsRun, retries); + } + /// /// Computes the maximum number of pickup poll attempts that fit inside /// , given the fixed initial delay and a @@ -6974,14 +7021,23 @@ internal static int ComputeMaxPollRetries(int delaySeconds) => // summarized once at Info below — not a Warning per attempt, and not a poll error. int notGeneratedYet = 0; string lastStates = null; + int attemptsRun = 0; + var deadline = _enrollDeadline.Value; + bool stoppedByDeadline = false; try { // Small static delay before the first poll — mirrors the V1 method's attempt to - // let a fast order finish issuing before we start polling at all. - await Task.Delay(TimeSpan.FromSeconds(Constants.Pickup.InitialDelaySeconds), ct); - - for (int attempt = 1; attempt <= retries; attempt++) + // let a fast order finish issuing before we start polling at all. The enrollment + // deadline can shorten it, or skip the pickup when no poll fits (a slow create or + // reissue already used the budget). + stoppedByDeadline = !EnrollmentDeadline.TryGetWait( + deadline, TimeSpan.FromSeconds(Constants.Pickup.InitialDelaySeconds), out TimeSpan initialWait); + if (!stoppedByDeadline) + await PickupDelayAsync(initialWait, ct); + + for (int attempt = 1; attempt <= retries && !stoppedByDeadline; attempt++) { + attemptsRun = attempt; try { var tracked = await _client.TrackOrderV2Async(productFamilySlug, orderId, ct); @@ -7097,32 +7153,41 @@ internal static int ComputeMaxPollRetries(int delaySeconds) => } // Delay after every attempt (including the last), matching the V1 method's - // pickup cadence so the max-occupancy ceiling is identical. - await Task.Delay(TimeSpan.FromSeconds(delaySeconds), ct); + // pickup cadence so the max-occupancy ceiling is identical. Under an enrollment + // deadline the delay after the last attempt is skipped (no poll follows it), and + // the others are shortened or end the pickup when no poll fits. + if (deadline != null && attempt == retries) + break; + stoppedByDeadline = !EnrollmentDeadline.TryGetWait( + deadline, TimeSpan.FromSeconds(delaySeconds), out TimeSpan wait); + if (!stoppedByDeadline) + await PickupDelayAsync(wait, ct); } // SOC1 accuracy: don't attribute non-completion to "still validating" when the // real cause was every poll erroring (e.g. a CA-side TrackOrder outage). Distinguish // the two so the log reflects what actually happened. - if (pollErrors == retries) + if (attemptsRun > 0 && pollErrors == attemptsRun) _logger.LogWarning( "V2 synchronous pickup exhausted {Retries} attempts for order {OrderId} — ALL polls " + "errored (see preceding warnings). Returning pending result; the next synchronization " + "will re-attempt retrieval.", - retries, orderId); + attemptsRun, orderId); else if (notGeneratedYet > 0) _logger.LogInformation( "V2 order {OrderId} is issued at CERTInext but its certificate was not generated yet after " + "{NotGenerated} of {Retries} pickup attempt(s) (Download Certificate answered 422 EMS-1165 each " + "time; normal generation takes about 20 s). {States}. Returning pending result; the " + "certificate will be imported by the next synchronization.", - orderId, notGeneratedYet, retries, lastStates); - else + orderId, notGeneratedYet, attemptsRun, lastStates); + else if (!stoppedByDeadline) _logger.LogInformation( "V2 synchronous pickup did not complete within {Retries} attempts for order {OrderId} " + "({Errors} poll error(s); remainder still pending). Returning pending result; the " + "certificate will be imported by the next synchronization.", - retries, orderId, pollErrors); + attemptsRun, orderId, pollErrors); + if (stoppedByDeadline) + LogPickupStoppedByDeadline(orderId, deadline, attemptsRun, retries); pendingResult.StatusMessage = notGeneratedYet > 0 ? $"{pendingResult.StatusMessage} The order is issued at CERTInext but its certificate was not " + "generated yet within the enrollment-pickup window; it will be imported by a later synchronization." diff --git a/CERTInext/CERTInextCAPluginConfig.cs b/CERTInext/CERTInextCAPluginConfig.cs index 35cedee..4030775 100644 --- a/CERTInext/CERTInextCAPluginConfig.cs +++ b/CERTInext/CERTInextCAPluginConfig.cs @@ -332,11 +332,24 @@ public static Dictionary GetCAConnectorAnnotations() $"are set, reducing the retry count to fit. Keep your configured total well under that " + $"ceiling. Default: {Constants.Pickup.DefaultDelaySeconds} " + $"(~{Constants.Pickup.InitialDelaySeconds + Constants.Pickup.DefaultRetries * Constants.Pickup.DefaultDelaySeconds} " + - $"s with default retries).", + $"s with default retries). EnrollmentCallBudgetSeconds also ends the wait early.", Hidden = false, DefaultValue = Constants.Pickup.DefaultDelaySeconds, Type = "Number" }, + [Constants.Config.EnrollmentCallBudgetSeconds] = new PropertyConfigInfo + { + Comments = $"OPTIONAL: Seconds from the start of an enrollment after which the certificate pickup " + + $"stops waiting and returns the order as pending (0 disables; at most " + + $"{Constants.Pickup.MaxEnrollmentCallBudgetSeconds}). Command fails an enrollment still " + + $"running at its Workflow Step Run Timeout application setting (60 s by default), even " + + $"though the order exists at CERTInext. If you raise that setting, set this about 10 s " + + $"lower. Order and reissue calls already in flight are never cut short. Default: " + + $"{Constants.Pickup.DefaultEnrollmentCallBudgetSeconds}.", + Hidden = false, + DefaultValue = Constants.Pickup.DefaultEnrollmentCallBudgetSeconds, + Type = "Number" + }, [Constants.Config.DcvEnabled] = new PropertyConfigInfo { Comments = "OPTIONAL: When true, the plugin performs DNS-based Domain Control Validation (DCV) " + @@ -943,6 +956,14 @@ public class CERTInextConfig [JsonPropertyName("PickupDelay")] public int PickupDelayInSeconds { get; set; } = Constants.Pickup.DefaultDelaySeconds; + /// + /// Seconds from Enroll() entry after which the certificate pickup stops waiting and + /// returns pending. Set it about 10 s below Command's "Workflow Step Run Timeout (seconds)" + /// application setting. 0 disables the deadline. Default: 50. + /// + [JsonPropertyName("EnrollmentCallBudgetSeconds")] + public int EnrollmentCallBudgetSeconds { get; set; } = Constants.Pickup.DefaultEnrollmentCallBudgetSeconds; + [JsonPropertyName("DcvPropagationDelaySeconds")] public int DcvPropagationDelaySeconds { get; set; } = 30; @@ -1116,5 +1137,20 @@ public int GetEffectivePickupDelaySeconds() => System.Math.Max(1, System.Math.Min( PickupDelayInSeconds > 0 ? PickupDelayInSeconds : Constants.Pickup.DefaultDelaySeconds, Constants.Pickup.MaxDelaySeconds)); + + /// + /// Effective enrollment-call budget in seconds: 0 (no deadline) when configured as 0, the + /// default when negative, otherwise clamped to + /// . + /// + public int GetEffectiveEnrollmentCallBudgetSeconds() + { + if (EnrollmentCallBudgetSeconds == 0) + return 0; + int configured = EnrollmentCallBudgetSeconds > 0 + ? EnrollmentCallBudgetSeconds + : Constants.Pickup.DefaultEnrollmentCallBudgetSeconds; + return System.Math.Min(configured, Constants.Pickup.MaxEnrollmentCallBudgetSeconds); + } } } diff --git a/CERTInext/Constants.cs b/CERTInext/Constants.cs index 61a192f..b420825 100644 --- a/CERTInext/Constants.cs +++ b/CERTInext/Constants.cs @@ -36,6 +36,10 @@ public static class Config public const string PickupRetries = "PickupRetries"; public const string PickupDelay = "PickupDelay"; + // Seconds from Enroll() entry after which the pickup stops waiting and returns pending, + // so the call returns before Command's "Workflow Step Run Timeout" (60 s by default). + public const string EnrollmentCallBudgetSeconds = "EnrollmentCallBudgetSeconds"; + public const string RequestorName = "RequestorName"; public const string RequestorEmail = "RequestorEmail"; public const string RequestorIsdCode = "RequestorIsdCode"; @@ -428,6 +432,23 @@ public static class Pickup // headroom inside the 100s Command budget for the order submit (plus DCV/CSR calls on V2) // and per-poll round-trips, which also consume that budget but aren't counted in this ceiling. public const int MaxTotalWaitSeconds = 75; + + // Deadline for the whole Enroll() call, measured from entry (EnrollmentCallBudgetSeconds). + // Command runs the Keyfactor-Enroll workflow step under the global application setting + // "Workflow Step Run Timeout (seconds)" (Workflow.General.Timeout), 60 s by default; a step + // still running then is failed even though the order exists at CERTInext. 50 s leaves about + // 10 s for Command-to-gateway transit and the response. The pickup is counted from its own + // start, so without this deadline the create/reissue time (a reissue alone took 26 s live) + // pushed the default 55 s pickup past the step timeout. 0 disables the deadline. + public const int DefaultEnrollmentCallBudgetSeconds = 50; + + // Upper clamp: below the 100 s HttpClient timeout on Command's call into the gateway, which + // applies whatever the workflow step timeout is set to. + public const int MaxEnrollmentCallBudgetSeconds = 90; + + // Time kept back for the poll itself (Track Order plus a download on V2) when the deadline + // shortens a wait, so the last poll also finishes inside the budget. + public const int DeadlinePollMarginSeconds = 3; } public static class Dcv diff --git a/CERTInext/EnrollmentDeadline.cs b/CERTInext/EnrollmentDeadline.cs new file mode 100644 index 0000000..5922e10 --- /dev/null +++ b/CERTInext/EnrollmentDeadline.cs @@ -0,0 +1,57 @@ +// Copyright 2026 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 System; + +namespace Keyfactor.Extensions.CAPlugin.CERTInext +{ + /// + /// The EnrollmentCallBudgetSeconds deadline for one Enroll() call, measured from + /// entry. It only gates waiting: the pickup's initial delay and the delays between polls are + /// shortened or skipped so the call returns before Command's workflow step timeout. Calls already + /// in flight (create, reissue, Submit CSR) are never cut short. + /// + internal sealed class EnrollmentDeadline + { + private readonly TimeProvider _clock; + private readonly long _startTimestamp; + + public EnrollmentDeadline(TimeProvider clock, TimeSpan budget) + { + _clock = clock; + _startTimestamp = clock.GetTimestamp(); + Budget = budget; + } + + public TimeSpan Budget { get; } + + public TimeSpan Elapsed => _clock.GetElapsedTime(_startTimestamp); + + public TimeSpan Remaining => Budget - Elapsed; + + /// + /// Decides how long the pickup may wait before its next poll. Returns false when the time left + /// can't fit another poll (); otherwise + /// is , shortened so the poll after it still + /// starts with the margin in hand. A null deadline never shortens anything. + /// + public static bool TryGetWait(EnrollmentDeadline deadline, TimeSpan desired, out TimeSpan wait) + { + wait = desired; + if (deadline == null) + return true; + + TimeSpan available = deadline.Remaining - TimeSpan.FromSeconds(Constants.Pickup.DeadlinePollMarginSeconds); + if (available <= TimeSpan.Zero) + return false; + + if (available < desired) + wait = available; + return true; + } + } +} diff --git a/CHANGELOG.md b/CHANGELOG.md index 3fbad8c..a15d675 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -33,6 +33,7 @@ - fix(enroll): V2 order and CSR submissions are never auto-retried after a timeout, which could create duplicate orders (V1 since 1.0.1). - fix(sync): A V2 order that `/reports/orders` lists but Track Order finds in no product family (seen for every `On Hold | Setup Pending` row) is skipped with one Information line and counted as `UntrackableListedOrders` in the sync summary. It used to log an error with a stack trace and count toward the sync's 25% error-rate abort. - fix(sync): The V2 sync summary lists every `orderStatus | certificateStatus` pair from `/reports/orders` that the plugin didn't recognize, with counts (`UnmappedReportStatuses=[...]`), at Information. CERTInext doesn't document these values, so new ones now show up in ordinary logs. +- fix(enroll): New setting `EnrollmentCallBudgetSeconds` (default 50, `0` disables, at most 90). It bounds the in-call pickup wait by a deadline measured from the start of `Enroll`, so time spent creating or reissuing the order counts against it. Before, the 55 s default pickup started only after the create (a V2 reissue alone took about 26 s live), so Command failed the enrollment at its 60 s Workflow Step Run Timeout while the order went on at CERTInext. That invited a resubmit and a duplicate order. The pickup now shortens its waits, skips the delay after its last poll, and returns pending with one Information line when no further poll fits. Calls already in flight are never cut short, and `PickupRetries=0` still disables the pickup. Set it about 10 s below Command's Workflow Step Run Timeout if you raise that (V1 and V2). - fix(dcv): V2 DCV looks each domain up (`GET /domains`) once per sync pass, and once per `Enroll` or single-record call, instead of once per pending order and SAN. Found rows and "no row" are reused; a failed lookup is not, so the next order on that domain tries again. - fix(sync): A V2 `/reports/orders` row that reads `Order Fulfilled | Pending for Approver` is resolved through Track Order, which returns `issued`, so the certificate is downloaded. It used to be reported as pending and never downloaded. Other disagreeing pairs, such as `Order Accepted | Certificate Revoked`, keep their mapping, because the certificate status is correct for them. - fix(v2): A V2 OAuth2 token request that gets no HTTP response (a dropped connection or other transport error) is retried twice, after 1 s and 3 s, so one network blip no longer fails an enrollment, a sync or a connector save. HTTP errors (400/401/403) are not retried, and order creates are still never retried. Token failures and other V2 calls with no response now log the transport detail (`TransportDetail=`: RestSharp's response status and the exception types and messages, with credentials removed) and include a short form in the error, instead of only `HttpStatus=0`. @@ -72,7 +73,7 @@ - The V2 incremental sync doesn't yet skip orders the gateway already holds unchanged, as the V1 incremental sync does from 1.0.2, so it re-reads each order listed. - Without a template `ProductCode`, the product CERTInext resolves depends on the account's catalog. Where several products match a variant, CERTInext may pick one that rejects a client CSR. On the sandbox, plain DV resolves to `917` "SSL DV 1 month" instead of `842`. Set `ProductCode` on the template to choose the product. - DCV for domains validated by SSL.com is built from the V2 spec and unit-tested but not verified live (the sandbox has no SSL.com-validated domains). Only SSL.com's `dns-txt` option can be published, because the DNS provider interface publishes TXT records only; a domain offered only `dns-cname` or `http-url` stays pending. -- Command's enrollment workflow can give up at 60 s, before the 75 s pickup ceiling. When it does, Command records the enrollment as failed even though the order continues at CERTInext, so the certificate can only arrive through a later sync. +- Inline DCV during `Enroll` isn't bounded by `EnrollmentCallBudgetSeconds` (it has its own `DcvTimeoutMinutes`), so an enrollment that runs DCV inline can still outlast Command's Workflow Step Run Timeout (60 s by default). Command then records the enrollment as failed even though the order continues at CERTInext, and the certificate arrives through a later sync. Raise that Command setting if inline DCV is slow. # 1.0.2 diff --git a/docsource/architecture.md b/docsource/architecture.md index df72ec4..1f9d2a4 100644 --- a/docsource/architecture.md +++ b/docsource/architecture.md @@ -358,7 +358,7 @@ sequenceDiagram - **Rate limiting.** A rate-limit rejection (`Inactive Account User.`) on order placement is retried with backoff before the failure is surfaced. - **Failures after the order is placed.** The order already exists at CERTInext, so a failed `TrackOrder` status check or a failed in-call DCV or issuance wait is logged as a warning and the enrollment returns pending with the order number. Failing instead would hide the order number from Command and let a retry place a duplicate paid order. A later synchronization finishes the order. - **DCV that skips a domain.** If DCV validates some domains but skips others (for example an IP or email SAN with no DNS provider), the validated domains are still verified and cleaned up, but `Enroll` does not wait for issuance, because the order cannot issue yet. It returns pending and the sync-driven DCV retry picks the order up. -- **Synchronous pickup.** After placing an order, the plugin polls CERTInext up to `PickupRetries` times (default 5), `PickupDelay` seconds apart (default 10), after a fixed 5-second initial delay and within a hard ceiling of 75 seconds, which keeps the call inside Command's own enrollment timeout of about 100 seconds. This lets fast-issuing DV certificates come back in the same enrollment call; only a result with a certificate body counts as issued. +- **Synchronous pickup.** After placing an order, the plugin polls CERTInext up to `PickupRetries` times (default 5), `PickupDelay` seconds apart (default 10), after a fixed 5-second initial delay and within a hard ceiling of 75 seconds. The wait also stops at `EnrollmentCallBudgetSeconds` (default 50) measured from the start of `Enroll`, so the call returns before Command's 60-second default workflow step timeout even after a slow create or reissue. This lets fast-issuing DV certificates come back in the same enrollment call; only a result with a certificate body counts as issued. #### V1 renewal and RenewOrReissue diff --git a/docsource/configuration.md b/docsource/configuration.md index 407b6fd..1a848d3 100644 --- a/docsource/configuration.md +++ b/docsource/configuration.md @@ -239,6 +239,7 @@ Calling `GetProductDetails` against your account lists the codes available to yo | `SyncRecentOrderGraceSeconds` | Both | Optional | A sync (full or incremental) skips pending or issued orders created less than this many seconds ago (plus a 5-second clock margin); the next incremental sync imports them. This keeps a sync that runs during an in-flight enrollment from causing that enrollment to fail with a duplicate key. `0` disables it. Default: `120`. | | `PickupRetries` | Both | Optional | Times `Enroll` polls CERTInext for the certificate after a successful order. `0` disables the wait. Default: `5`. | | `PickupDelay` | Both | Optional | Seconds between pickup polls. Default: `10`. | +| `EnrollmentCallBudgetSeconds` | Both | Optional | Seconds from the start of an enrollment after which the pickup stops waiting and returns the order as pending, so the call returns before Command's workflow step timeout. Set it about 10 s below Command's **Workflow Step Run Timeout (seconds)** application setting. `0` disables it. Default: `50`. Maximum: `90`. | - **`IgnoreExpired` on V1:** the V1 sync maps no certificate expiry date, so the filter never matches and expired certificates are still imported. The V2 sync applies it. - **`PageSize` limits:** values above the maximum are clamped. On V2, a value of 0 or less falls back to 100. On V1, a value below 1 is not corrected, so keep it at 1 or higher. @@ -251,6 +252,7 @@ Calling `GetProductDetails` against your account lists the codes available to yo | `PickupRetries` | 0 (disabled) | 30 | 5 | Negative becomes 0; above 30 becomes 30 | | `PickupDelay` (seconds) | 1 | 60 | 10 | Zero or negative becomes 10; above 60 becomes 60 | | Total wait | — | 75 s | ~55 s | The retry count is reduced to fit the cap | +| `EnrollmentCallBudgetSeconds` | 0 (no deadline) | 90 | 50 | Negative becomes 50; above 90 becomes 90 | > **Pickup timing detail:** after a successful order placement, the plugin waits a fixed 5-second initial delay before the first poll, then polls CERTInext every `PickupDelay` seconds up to `PickupRetries` times. Each poll calls `GetCertificate` to check whether the certificate has been issued. The total time budget is **5 s + (`PickupRetries` × `PickupDelay`) + about 1 s API round trip per poll**. With the defaults this is 5 + (5 × 10) = **~55 s plus round trips**. > @@ -265,6 +267,17 @@ Calling `GetProductDetails` against your account lists the codes available to yo > > The 5-second initial delay is not configurable, and the 75-second ceiling applies regardless of configuration. It sits inside Command's roughly 100-second enrollment-call timeout, which leaves headroom for order submission and per-poll round trips. When the DCV flow ran for the order inside the same `Enroll` call, the pickup poll is skipped, because the DCV flow already waited for issuance. +#### Command's workflow step timeout and `EnrollmentCallBudgetSeconds` + +Command runs the gateway enrollment inside the **Keyfactor-Enroll** step of the enrollment workflow. The step is bounded by the global application setting **Workflow Step Run Timeout (seconds)** (System Settings > Application Settings > Workflow > General; API short name `Workflow.General.Timeout`), which defaults to 60. The step itself has no timeout field of its own. If the plugin's `Enroll` call is still running when that time is up, Command fails the request with "Step 'Keyfactor-Enroll' failed: Failed to complete in 60 seconds", even though the order already exists at CERTInext. The certificate then arrives only through a later sync, and a resubmit creates a duplicate order. + +The pickup budget above is counted from the start of the pickup, so the time spent placing the order is added on top of it. On the lab, a new V2 order's create took about 1 s and the pickup started about 3 s after `Enroll` was called; a V2 reissue call alone took about 26 s. With the default 55 s pickup, both ran past 60 s when the certificate wasn't ready. + +`EnrollmentCallBudgetSeconds` (default 50) is a deadline measured from the start of `Enroll`. The pickup shortens its waits to fit inside it, skips the delay after its last poll, and stops early, returning the order as pending, when no further poll fits (it keeps a 3-second margin for the poll itself). It logs one Information line saying how much of the budget had passed and how many polls ran. The deadline only limits waiting: a create, reissue, Submit CSR or revoke call already in flight is never cut short, and orders are still never retried. `PickupRetries=0` still disables the pickup entirely. Inline DCV during `Enroll` isn't bounded by this deadline (it has its own `DcvTimeoutMinutes`), so an enrollment that runs DCV inline can still exceed the workflow step timeout. + +- **If you raise Workflow Step Run Timeout**, for example because DNS propagation is slow, raise `EnrollmentCallBudgetSeconds` to about 10 s less than the new value. The 10 s leaves time for the Command-to-gateway call and the response. +- **The maximum is 90 s.** Separately from the workflow setting, Command's HTTP call into the gateway uses the .NET default timeout of 100 s, and no Command setting for it is documented. Neither the Command API nor the documentation states a maximum for Workflow Step Run Timeout. + ### Domain Control Validation (DCV) DCV needs a DNS provider plugin (for example `azure-azuredns-dnsplugin`) deployed on the gateway. Without one, orders that need validation stay pending and the plugin logs why. diff --git a/docsource/overview.md b/docsource/overview.md index 6695242..deb7a20 100644 --- a/docsource/overview.md +++ b/docsource/overview.md @@ -85,7 +85,7 @@ This is the expected result in any of these cases: - **OV or EV order:** CERTInext issues these after organization verification (minutes to hours), longer than the enrollment call waits. - **DCV enabled but unable to run:** no DNS provider plugin is deployed on the gateway, or none resolves the order's domain. The plugin logs why. The order completes only after the domain is validated some other way. - **`Enroll()` budget elapsed:** the plugin's bounded wait ended before CERTInext finished issuing. The budget is: - - `PickupRetries` × `PickupDelay` for the certificate pickup poll, capped at 75 s in total (inside Command's roughly 100 s enrollment-call timeout); + - `PickupRetries` × `PickupDelay` for the certificate pickup poll, capped at 75 s in total and ended at `EnrollmentCallBudgetSeconds` (default 50 s from the start of the enrollment, inside Command's 60 s default workflow step timeout); - on V1, `DcvWaitForChallengeSeconds` + `DcvWaitForIssuanceSeconds` (default 60 s each) around DCV. When DCV engages for an order, these waits replace the pickup wait; they do not stack. - **Issued but certificate not generated yet (V2):** CERTInext reports the order `issued` while Download Certificate still answers 422 `EMS-1165`. Normal generation takes about 20 s; the pickup poll waits for it, logging at Debug level and writing one Information summary. If the budget runs out the next sync imports the certificate. - **DCV could not validate every domain:** for example an IP or email SAN with no DNS provider. V1 still validates the other domains but returns pending without waiting for issuance. diff --git a/integration-manifest.json b/integration-manifest.json index 5aaa0b5..862b57f 100644 --- a/integration-manifest.json +++ b/integration-manifest.json @@ -258,11 +258,18 @@ }, { "name": "PickupDelay", - "description": "OPTIONAL: Seconds between certificate-pickup polls (1-60). Total wait is 5 s + PickupRetries x this value. Command's own enrollment call into the gateway is bounded at roughly 100 s, so the plugin caps the total at 75 s regardless of how PickupRetries/PickupDelay are set, reducing the retry count to fit. Keep your configured total well under that ceiling. Default: 10 (~55 s with default retries).", + "description": "OPTIONAL: Seconds between certificate-pickup polls (1-60). Total wait is 5 s + PickupRetries x this value. Command's own enrollment call into the gateway is bounded at roughly 100 s, so the plugin caps the total at 75 s regardless of how PickupRetries/PickupDelay are set, reducing the retry count to fit. Keep your configured total well under that ceiling. Default: 10 (~55 s with default retries). EnrollmentCallBudgetSeconds also ends the wait early.", "required": "Optional", "example": "10", "default": "10" }, + { + "name": "EnrollmentCallBudgetSeconds", + "description": "OPTIONAL: Seconds from the start of an enrollment after which the certificate pickup stops waiting and returns the order as pending (0 disables; at most 90). Command fails an enrollment still running at its Workflow Step Run Timeout application setting (60 s by default), even though the order exists at CERTInext. If you raise that setting, set this about 10 s lower. Order and reissue calls already in flight are never cut short. Default: 50.", + "required": "Optional", + "example": "50", + "default": "50" + }, { "name": "DcvEnabled", "description": "OPTIONAL: When true, the plugin performs DNS-based Domain Control Validation (DCV) during enrollment and synchronization for orders that require it, using the DNS provider plugin deployed on the gateway (e.g. azure-azuredns-dnsplugin). Without a DNS provider plugin, orders that need validation stay pending and the plugin logs why. Set to false to skip DCV. Default: true.", From f37a6e993701c2c8d86d479711c96e78689d672a Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" Date: Sat, 14 Nov 2026 21:16:30 +0000 Subject: [PATCH 04/11] docs: auto-generate README and documentation [skip ci] --- README.md | 22 ++++++++++++++++++---- 1 file changed, 18 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 1ccdab6..28b6db7 100644 --- a/README.md +++ b/README.md @@ -192,7 +192,8 @@ CERTInext operates three separate environments. Use the sandbox environment for * **Enabled** - Enables or disables the CA connector. Set to false to create the connector record before credentials are available. Default: true. * **LogSensitiveRequestData** - OPTIONAL temporary diagnostic switch. When true, requestor personal data (name, email, phone) and full CA payloads are logged. Credentials are always redacted. Turn off after verifying. Default: false. * **PickupRetries** - OPTIONAL: Times Enroll() polls CERTInext for the certificate after order submission (0-30; 0 disables the wait). Unissued orders are picked up by sync. Default: 5. - * **PickupDelay** - OPTIONAL: Seconds between certificate-pickup polls (1-60). Total wait is 5 s + PickupRetries x this value. Command's own enrollment call into the gateway is bounded at roughly 100 s, so the plugin caps the total at 75 s regardless of how PickupRetries/PickupDelay are set, reducing the retry count to fit. Keep your configured total well under that ceiling. Default: 10 (~55 s with default retries). + * **PickupDelay** - OPTIONAL: Seconds between certificate-pickup polls (1-60). Total wait is 5 s + PickupRetries x this value. Command's own enrollment call into the gateway is bounded at roughly 100 s, so the plugin caps the total at 75 s regardless of how PickupRetries/PickupDelay are set, reducing the retry count to fit. Keep your configured total well under that ceiling. Default: 10 (~55 s with default retries). EnrollmentCallBudgetSeconds also ends the wait early. + * **EnrollmentCallBudgetSeconds** - OPTIONAL: Seconds from the start of an enrollment after which the certificate pickup stops waiting and returns the order as pending (0 disables; at most 90). Command fails an enrollment still running at its Workflow Step Run Timeout application setting (60 s by default), even though the order exists at CERTInext. If you raise that setting, set this about 10 s lower. Order and reissue calls already in flight are never cut short. Default: 50. * **DcvEnabled** - OPTIONAL: When true, the plugin performs DNS-based Domain Control Validation (DCV) during enrollment and synchronization for orders that require it, using the DNS provider plugin deployed on the gateway (e.g. azure-azuredns-dnsplugin). Without a DNS provider plugin, orders that need validation stay pending and the plugin logs why. Set to false to skip DCV. Default: true. * **DcvTxtRecordTemplate** - OPTIONAL: Format string for the DNS TXT record hostname used during DCV. {0} is replaced with the domain name being validated. Default: _emsign-validation.{0} * **DcvPropagationDelaySeconds** - OPTIONAL: Seconds to wait after publishing the DNS TXT record before asking CERTInext to verify it. Increase for zones with slow propagation. Default: 30. @@ -413,6 +414,7 @@ Calling `GetProductDetails` against your account lists the codes available to yo | `SyncRecentOrderGraceSeconds` | Both | Optional | A sync (full or incremental) skips pending or issued orders created less than this many seconds ago (plus a 5-second clock margin); the next incremental sync imports them. This keeps a sync that runs during an in-flight enrollment from causing that enrollment to fail with a duplicate key. `0` disables it. Default: `120`. | | `PickupRetries` | Both | Optional | Times `Enroll` polls CERTInext for the certificate after a successful order. `0` disables the wait. Default: `5`. | | `PickupDelay` | Both | Optional | Seconds between pickup polls. Default: `10`. | +| `EnrollmentCallBudgetSeconds` | Both | Optional | Seconds from the start of an enrollment after which the pickup stops waiting and returns the order as pending, so the call returns before Command's workflow step timeout. Set it about 10 s below Command's **Workflow Step Run Timeout (seconds)** application setting. `0` disables it. Default: `50`. Maximum: `90`. | - **`IgnoreExpired` on V1:** the V1 sync maps no certificate expiry date, so the filter never matches and expired certificates are still imported. The V2 sync applies it. - **`PageSize` limits:** values above the maximum are clamped. On V2, a value of 0 or less falls back to 100. On V1, a value below 1 is not corrected, so keep it at 1 or higher. @@ -425,6 +427,7 @@ Calling `GetProductDetails` against your account lists the codes available to yo | `PickupRetries` | 0 (disabled) | 30 | 5 | Negative becomes 0; above 30 becomes 30 | | `PickupDelay` (seconds) | 1 | 60 | 10 | Zero or negative becomes 10; above 60 becomes 60 | | Total wait | — | 75 s | ~55 s | The retry count is reduced to fit the cap | +| `EnrollmentCallBudgetSeconds` | 0 (no deadline) | 90 | 50 | Negative becomes 50; above 90 becomes 90 | > **Pickup timing detail:** after a successful order placement, the plugin waits a fixed 5-second initial delay before the first poll, then polls CERTInext every `PickupDelay` seconds up to `PickupRetries` times. Each poll calls `GetCertificate` to check whether the certificate has been issued. The total time budget is **5 s + (`PickupRetries` × `PickupDelay`) + about 1 s API round trip per poll**. With the defaults this is 5 + (5 × 10) = **~55 s plus round trips**. > @@ -439,6 +442,17 @@ Calling `GetProductDetails` against your account lists the codes available to yo > > The 5-second initial delay is not configurable, and the 75-second ceiling applies regardless of configuration. It sits inside Command's roughly 100-second enrollment-call timeout, which leaves headroom for order submission and per-poll round trips. When the DCV flow ran for the order inside the same `Enroll` call, the pickup poll is skipped, because the DCV flow already waited for issuance. +#### Command's workflow step timeout and `EnrollmentCallBudgetSeconds` + +Command runs the gateway enrollment inside the **Keyfactor-Enroll** step of the enrollment workflow. The step is bounded by the global application setting **Workflow Step Run Timeout (seconds)** (System Settings > Application Settings > Workflow > General; API short name `Workflow.General.Timeout`), which defaults to 60. The step itself has no timeout field of its own. If the plugin's `Enroll` call is still running when that time is up, Command fails the request with "Step 'Keyfactor-Enroll' failed: Failed to complete in 60 seconds", even though the order already exists at CERTInext. The certificate then arrives only through a later sync, and a resubmit creates a duplicate order. + +The pickup budget above is counted from the start of the pickup, so the time spent placing the order is added on top of it. On the lab, a new V2 order's create took about 1 s and the pickup started about 3 s after `Enroll` was called; a V2 reissue call alone took about 26 s. With the default 55 s pickup, both ran past 60 s when the certificate wasn't ready. + +`EnrollmentCallBudgetSeconds` (default 50) is a deadline measured from the start of `Enroll`. The pickup shortens its waits to fit inside it, skips the delay after its last poll, and stops early, returning the order as pending, when no further poll fits (it keeps a 3-second margin for the poll itself). It logs one Information line saying how much of the budget had passed and how many polls ran. The deadline only limits waiting: a create, reissue, Submit CSR or revoke call already in flight is never cut short, and orders are still never retried. `PickupRetries=0` still disables the pickup entirely. Inline DCV during `Enroll` isn't bounded by this deadline (it has its own `DcvTimeoutMinutes`), so an enrollment that runs DCV inline can still exceed the workflow step timeout. + +- **If you raise Workflow Step Run Timeout**, for example because DNS propagation is slow, raise `EnrollmentCallBudgetSeconds` to about 10 s less than the new value. The 10 s leaves time for the Command-to-gateway call and the response. +- **The maximum is 90 s.** Separately from the workflow setting, Command's HTTP call into the gateway uses the .NET default timeout of 100 s, and no Command setting for it is documented. Neither the Command API nor the documentation states a maximum for Workflow Step Run Timeout. + ### Domain Control Validation (DCV) DCV needs a DNS provider plugin (for example `azure-azuredns-dnsplugin`) deployed on the gateway. Without one, orders that need validation stay pending and the plugin logs why. @@ -646,7 +660,7 @@ mapped to Failed — see the gateway trace log if certificates unexpectedly show **V2 synchronization:** - Synchronize pages through `/reports/orders`. Pages are capped at 100 rows, and `PageSize` is clamped to that. -- The report carries display strings (for example `Order Fulfilled`, `Certificate Downloaded`) rather than the status enum above. Recognized strings are mapped directly. Any other combination falls back to a live order-status call, so a new display value never silently misclassifies an order. If that call finds the order in no product family, as for every `On Hold | Setup Pending` row on the sandbox, the order is skipped for that pass and counted as `UntrackableListedOrders`; it isn't treated as an error. CERTInext doesn't document these display strings, so the sync summary names every pair it didn't recognize (`UnmappedReportStatuses=[...]`). Report a new pair so it can be mapped. +- The report carries display strings (for example `Order Fulfilled`, `Certificate Downloaded`) rather than the status enum above. Recognized strings are mapped directly. Any other combination falls back to a live order-status call, so a new display value never silently misclassifies an order. If that call finds the order in no product family, as for every `On Hold | Setup Pending` row on the sandbox, the order is skipped for that pass and counted as `UntrackableListedOrders`; it isn't treated as an error. CERTInext doesn't document these display strings, so the sync summary names every pair it didn't recognize (`UnmappedReportStatuses=[...]`). Report a new pair so it can be mapped. One known pair is deliberately left unmapped: `Order Fulfilled | Pending for Approver` (the order fulfilled, the certificate still pending). Track Order returns `issued` for it, so the plugin asks Track Order and downloads the certificate instead of reporting the order as pending. - Cancelled and rejected orders are skipped. Issued orders have their certificate chain downloaded. - CERTInext does not serve the certificate body of a revoked order. A revoked order is propagated as revoked only when the gateway already holds that certificate (the revocation date and reason come from a live status call). - Otherwise a revoked order is reported as Failed (the gateway has a record without a body) or skipped (no record), so the gateway never stores a revoked record without a certificate. @@ -1239,7 +1253,7 @@ For an order that lists per-domain verification state (a multi-domain order, for ##### SSL.com-validated domains (V2) -Before it requests a challenge for a pending domain, the V2 flow looks the domain up (`GET /domains?search={domain}&exactMatch=true`). A domain whose row says `validatedBy: SSLCOM` uses the domain-level DCV endpoints instead of the order-level ones: +Before it requests a challenge for a pending domain, the V2 flow looks the domain up (`GET /domains?search={domain}&exactMatch=true`). Each sync pass, and each `Enroll` or single-record DCV attempt, looks a domain up once and reuses the answer, including "no row", for every other order on that domain. A failed lookup isn't reused, so the next order on that domain tries again. A domain whose row says `validatedBy: SSLCOM` uses the domain-level DCV endpoints instead of the order-level ones: 1. `GET /domains/{domainId}/dcv` returns SSL.com's record. If SSL.com reports the domain `VALIDATED`, step 2 is skipped. 2. The plugin picks a `dns-txt` option, preferring the selected one, then one for exactly this name. It publishes that `recordName` and `recordValue` through the DNS provider plugin and ignores `DcvTxtRecordTemplate`. `dns-cname` and `http-url` options are not used, because the DNS provider interface (`IAnyCAPlugin` 3.3) can only publish TXT records. @@ -1299,7 +1313,7 @@ sequenceDiagram - **Rate limiting.** A rate-limit rejection (`Inactive Account User.`) on order placement is retried with backoff before the failure is surfaced. - **Failures after the order is placed.** The order already exists at CERTInext, so a failed `TrackOrder` status check or a failed in-call DCV or issuance wait is logged as a warning and the enrollment returns pending with the order number. Failing instead would hide the order number from Command and let a retry place a duplicate paid order. A later synchronization finishes the order. - **DCV that skips a domain.** If DCV validates some domains but skips others (for example an IP or email SAN with no DNS provider), the validated domains are still verified and cleaned up, but `Enroll` does not wait for issuance, because the order cannot issue yet. It returns pending and the sync-driven DCV retry picks the order up. -- **Synchronous pickup.** After placing an order, the plugin polls CERTInext up to `PickupRetries` times (default 5), `PickupDelay` seconds apart (default 10), after a fixed 5-second initial delay and within a hard ceiling of 75 seconds, which keeps the call inside Command's own enrollment timeout of about 100 seconds. This lets fast-issuing DV certificates come back in the same enrollment call; only a result with a certificate body counts as issued. +- **Synchronous pickup.** After placing an order, the plugin polls CERTInext up to `PickupRetries` times (default 5), `PickupDelay` seconds apart (default 10), after a fixed 5-second initial delay and within a hard ceiling of 75 seconds. The wait also stops at `EnrollmentCallBudgetSeconds` (default 50) measured from the start of `Enroll`, so the call returns before Command's 60-second default workflow step timeout even after a slow create or reissue. This lets fast-issuing DV certificates come back in the same enrollment call; only a result with a certificate body counts as issued. #### V1 renewal and RenewOrReissue From 33681ec743e036a8b2d9cf2e539f18816255f7db Mon Sep 17 00:00:00 2001 From: spbsoluble <1661003+spbsoluble@users.noreply.github.com> Date: Sun, 15 Nov 2026 12:50:48 -0800 Subject: [PATCH 05/11] test(live): run the V2 sync for one 'Order Fulfilled | Pending for Approver' order Opt-in (CERTINEXT_V2_FULFILLED_PENDING_SYNC=1), read-only. A DispatchProxy narrows the real report listing to one order and forwards every other call to the real client, so the actual Synchronize path runs live. Asserts the row defers to Track Order, comes out issued, and has its certificate download attempted. Live 2026-11-15 on 1125823297: Track issued, download 422 EMS-1165 (never generated), emitted issued without a body. --- .../V2FulfilledPendingSyncLiveTests.cs | 146 ++++++++++++++++++ 1 file changed, 146 insertions(+) create mode 100644 CERTInext.IntegrationTests/V2FulfilledPendingSyncLiveTests.cs diff --git a/CERTInext.IntegrationTests/V2FulfilledPendingSyncLiveTests.cs b/CERTInext.IntegrationTests/V2FulfilledPendingSyncLiveTests.cs new file mode 100644 index 0000000..92f4c4f --- /dev/null +++ b/CERTInext.IntegrationTests/V2FulfilledPendingSyncLiveTests.cs @@ -0,0 +1,146 @@ +// Copyright 2026 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 System; +using System.Collections.Concurrent; +using System.Collections.Generic; +using System.Linq; +using System.Reflection; +using System.Runtime.CompilerServices; +using System.Runtime.ExceptionServices; +using System.Threading; +using System.Threading.Tasks; +using FluentAssertions; +using Keyfactor.AnyGateway.Extensions; +using Keyfactor.Extensions.CAPlugin.CERTInext.API.V2; +using Keyfactor.Extensions.CAPlugin.CERTInext.Client; +using Keyfactor.PKI.Enums.EJBCA; +using Org.BouncyCastle.X509; +using Xunit; +using Xunit.Abstractions; + +namespace Keyfactor.Extensions.CAPlugin.CERTInext.IntegrationTests +{ + /// + /// Plan 0096 item 2, live: a /reports/orders row reading Order Fulfilled | Pending for Approver + /// must go through Track Order and come out of the V2 sync as issued, with the certificate downloaded. + /// Runs the real Synchronize code against the live API, with the report listing narrowed to one + /// order by a forwarding proxy; every other call goes to the real client unchanged. Read-only at + /// CERTInext (list, track, download), DCV off. Opt-in: CERTINEXT_V2_FULFILLED_PENDING_SYNC=1; + /// order from CERTINEXT_V2_FULFILLED_PENDING_ORDER (default 1125823297). + /// + public class V2FulfilledPendingSyncLiveTests : IClassFixture + { + private readonly ITestOutputHelper _output; + private readonly Dictionary _env; + + public V2FulfilledPendingSyncLiveTests(IntegrationTestFixture fixture, ITestOutputHelper output) + { + _output = output; + _env = V2EnvHelper.LoadAndPromote(); + } + + /// Forwards every call to ; the report listing yields only . + public class OneOrderListingProxy : DispatchProxy + { + internal ICERTInextClient Inner; + internal string OrderId; + internal readonly ConcurrentQueue Calls = new ConcurrentQueue(); + internal int RowsListed; + + protected override object Invoke(MethodInfo targetMethod, object[] args) + { + Calls.Enqueue(targetMethod.Name); + object result; + try { result = targetMethod.Invoke(Inner, args); } + catch (TargetInvocationException tie) when (tie.InnerException != null) + { + ExceptionDispatchInfo.Capture(tie.InnerException).Throw(); + throw; + } + return targetMethod.Name == nameof(ICERTInextClient.ListOrdersV2Async) + ? OnlyTarget((IAsyncEnumerable)result) + : result; + } + + private async IAsyncEnumerable OnlyTarget( + IAsyncEnumerable rows, [EnumeratorCancellation] CancellationToken ct = default) + { + await foreach (var row in rows.WithCancellation(ct)) + { + RowsListed++; + if (string.Equals(row.OrderNumber, OrderId, StringComparison.Ordinal)) + yield return row; + } + } + } + + [SkippableFact] + public async Task Sync_OrderFulfilledPendingForApprover_TracksAndDownloads() + { + string apiUrl = V2EnvHelper.GetEnv(_env, "CERTINEXT_API_URL"); + string clientId = V2EnvHelper.GetEnv(_env, "CERTINEXT_CLIENT_ID"); + string clientSecret = V2EnvHelper.GetEnv(_env, "CERTINEXT_CLIENT_SECRET"); + Skip.If(string.IsNullOrWhiteSpace(V2EnvHelper.GetEnv(_env, "CERTINEXT_USE_V2_API")) + || string.IsNullOrWhiteSpace(apiUrl) || string.IsNullOrWhiteSpace(clientId) + || string.IsNullOrWhiteSpace(clientSecret) + || V2EnvHelper.GetEnv(_env, "CERTINEXT_V2_FULFILLED_PENDING_SYNC") != "1", + "Requires CERTINEXT_USE_V2_API + V2 credentials and CERTINEXT_V2_FULFILLED_PENDING_SYNC=1."); + string orderId = V2EnvHelper.GetEnv(_env, "CERTINEXT_V2_FULFILLED_PENDING_ORDER", "1125823297"); + + var config = new CERTInextConfig + { + ApiUrl = apiUrl, UseV2Api = true, OAuthClientId = clientId, OAuthClientSecret = clientSecret, + SignerPlace = "Gateway Lab", PageSize = 100, DcvEnabled = false + }; + var restoreLogging = TestOutputLogging.RouteTo(_output); + try + { + using var real = new CERTInextClient(config); + var proxy = DispatchProxy.Create(); + var p = (OneOrderListingProxy)(object)proxy; + p.Inner = real; + p.OrderId = orderId; + + using var plugin = new CERTInextCAPlugin(proxy, config); + var buffer = new BlockingCollection(10); + await plugin.Synchronize(buffer, null, true, CancellationToken.None); + + var calls = p.Calls.ToList(); + _output.WriteLine($"Report rows read: {p.RowsListed}; passed to sync: order {orderId} only."); + _output.WriteLine("Client calls: " + string.Join(", ", calls.GroupBy(c => c).Select(g => $"{g.Key} x{g.Count()}"))); + + var record = buffer.ToArray().Should().ContainSingle(r => r.CARequestID == orderId, + "the order must be emitted (it is not recent, failed, or untrackable)").Subject; + _output.WriteLine($"Emitted: CARequestID={record.CARequestID}, Status={record.Status}, ProductID={record.ProductID}, " + + $"HasCertificate={!string.IsNullOrWhiteSpace(record.Certificate)}"); + if (!string.IsNullOrWhiteSpace(record.Certificate)) + { + var cert = new X509CertificateParser().ReadCertificate(System.Text.Encoding.ASCII.GetBytes(record.Certificate)); + _output.WriteLine($"Certificate: Subject={cert.SubjectDN}, Serial={cert.SerialNumber.ToString(16).ToUpperInvariant()}, " + + $"NotBefore={cert.NotBefore:u}, NotAfter={cert.NotAfter:u}"); + } + + calls.Should().Contain(nameof(ICERTInextClient.ResolveAndTrackOrderV2WithFamilyAsync), + "the Fulfilled/Pending-for-Approver pair must defer to Track Order"); + record.Status.Should().Be((int)EndEntityStatus.GENERATED, "Track Order reports the order issued"); + calls.Should().Contain(nameof(ICERTInextClient.ResolveAndDownloadCertificateV2Async), + "an issued order's certificate is downloaded"); + // Whether a body comes back is CA state, not plugin behaviour. Live 2026-11-15: 1125823297 + // answered 422 EMS-1165 (never generated; see Finding 35 update), so it was emitted as + // issued without a body (sync summary IssuedNotGeneratedYet=1) for a later pass. + if (string.IsNullOrWhiteSpace(record.Certificate)) + _output.WriteLine("No certificate body: CERTInext reports the order issued but its certificate " + + "isn't generated (see IssuedNotGeneratedYet in the sync summary above)."); + } + finally + { + restoreLogging(); + } + } + } +} From 507d42ffc4a148cd5b74e11ccf88c16843eeb5eb Mon Sep 17 00:00:00 2001 From: spbsoluble <1661003+spbsoluble@users.noreply.github.com> Date: Mon, 16 Nov 2026 08:38:18 -0800 Subject: [PATCH 06/11] fix(sync): keep 'Order Fulfilled | Pending for Approver' pending when its certificate isn't generated Live on 1125823297: Track Order says issued, but Download Certificate answers 422 EMS-1165 for an order placed months before the sandbox stopped generating, so the report's 'Pending for Approver' was right. Such a row (Track fallback said issued, the report's certificate status maps to pending, download EMS-1165) is now emitted pending instead of issued without a certificate. The download is still tried every pass, so a certificate that appears is imported. Other download failures, and rows whose report doesn't say pending, keep the issued-without-body behaviour. --- .../V2FulfilledPendingSyncLiveTests.cs | 23 ++++--- .../V2SyncUnmappedStatusSummaryTests.cs | 61 +++++++++++++++++++ CERTInext/CERTInextCAPlugin.cs | 22 ++++++- CHANGELOG.md | 2 +- docsource/configuration.md | 2 +- 5 files changed, 99 insertions(+), 11 deletions(-) diff --git a/CERTInext.IntegrationTests/V2FulfilledPendingSyncLiveTests.cs b/CERTInext.IntegrationTests/V2FulfilledPendingSyncLiveTests.cs index 92f4c4f..ca5b8f0 100644 --- a/CERTInext.IntegrationTests/V2FulfilledPendingSyncLiveTests.cs +++ b/CERTInext.IntegrationTests/V2FulfilledPendingSyncLiveTests.cs @@ -27,7 +27,8 @@ namespace Keyfactor.Extensions.CAPlugin.CERTInext.IntegrationTests { /// /// Plan 0096 item 2, live: a /reports/orders row reading Order Fulfilled | Pending for Approver - /// must go through Track Order and come out of the V2 sync as issued, with the certificate downloaded. + /// must go through Track Order and have its certificate download tried: issued with the certificate when + /// one exists, pending (as the row's certificate status says) when the download answers EMS-1165. /// Runs the real Synchronize code against the live API, with the report listing narrowed to one /// order by a forwarding proxy; every other call goes to the real client unchanged. Read-only at /// CERTInext (list, track, download), DCV off. Opt-in: CERTINEXT_V2_FULFILLED_PENDING_SYNC=1; @@ -127,15 +128,21 @@ public async Task Sync_OrderFulfilledPendingForApprover_TracksAndDownloads() calls.Should().Contain(nameof(ICERTInextClient.ResolveAndTrackOrderV2WithFamilyAsync), "the Fulfilled/Pending-for-Approver pair must defer to Track Order"); - record.Status.Should().Be((int)EndEntityStatus.GENERATED, "Track Order reports the order issued"); calls.Should().Contain(nameof(ICERTInextClient.ResolveAndDownloadCertificateV2Async), - "an issued order's certificate is downloaded"); - // Whether a body comes back is CA state, not plugin behaviour. Live 2026-11-15: 1125823297 - // answered 422 EMS-1165 (never generated; see Finding 35 update), so it was emitted as - // issued without a body (sync summary IssuedNotGeneratedYet=1) for a later pass. + "Track Order reports the order issued, so its certificate download is tried"); + // Whether a body comes back is CA state. Live 2026-11-15: 1125823297 answered 422 EMS-1165 + // (never generated; Finding 35 update). With a certificate the order is issued; without one it + // stays pending, as the report's "Pending for Approver" says. if (string.IsNullOrWhiteSpace(record.Certificate)) - _output.WriteLine("No certificate body: CERTInext reports the order issued but its certificate " + - "isn't generated (see IssuedNotGeneratedYet in the sync summary above)."); + { + record.Status.Should().Be((int)EndEntityStatus.EXTERNALVALIDATION, + "no certificate was generated, so the report's pending certificate status stands"); + _output.WriteLine("No certificate body: download answered EMS-1165; emitted pending."); + } + else + { + record.Status.Should().Be((int)EndEntityStatus.GENERATED); + } } finally { diff --git a/CERTInext.Tests/V2SyncUnmappedStatusSummaryTests.cs b/CERTInext.Tests/V2SyncUnmappedStatusSummaryTests.cs index df68eb1..8585f30 100644 --- a/CERTInext.Tests/V2SyncUnmappedStatusSummaryTests.cs +++ b/CERTInext.Tests/V2SyncUnmappedStatusSummaryTests.cs @@ -111,5 +111,66 @@ public async Task Sync_OrderFulfilledPendingForApprover_TracksOnce_EmitsIssuedWi capture.Lines(LogLevel.Information, "synchronization complete").Should().ContainSingle() .Which.Should().Contain("UnmappedReportStatuses=[Order Fulfilled | Pending for Approver (1)]"); } + + private static readonly System.Exception Ems1165 = new System.Exception( + "CERTInext V2 API error during 'V2 download certificate'. HTTP 422. Unprocessable Entity: EMS-1165 Invalid request status."); + + private static (Mock Mock, CERTInextCAPlugin Plugin) TrackIssued( + string id, string orderStatus, string certificateStatus, System.Exception downloadError) + { + var mock = new Mock(); + mock.Setup(c => c.ListOrdersV2Async(It.IsAny(), It.IsAny(), It.IsAny(), It.IsAny())) + .Returns(Rows(Row(id, orderStatus, certificateStatus))); + mock.Setup(c => c.ResolveAndTrackOrderV2WithFamilyAsync(id, It.IsAny())) + .ReturnsAsync((Constants.ApiV2.FamilySsl, new V2OrderStatusResponse { OrderId = id, Status = "issued" })); + mock.Setup(c => c.ResolveAndDownloadCertificateV2Async(id, It.IsAny())).ThrowsAsync(downloadError); + var config = new CERTInextConfig { UseV2Api = true, ApiUrl = "https://v2.certinext.io", OAuthClientId = "id", OAuthClientSecret = "s" }; + return (mock, new CERTInextCAPlugin(mock.Object, config)); + } + + [Fact] + public async Task Sync_OrderFulfilledPendingForApprover_NotGenerated_EmittedPending() + { + // Live on 1125823297: Track says issued, Download answers EMS-1165, and the report's + // "Pending for Approver" was right. Pending, not issued-without-a-certificate. + using var capture = new PluginLogCapture(); + var (mock, plugin) = TrackIssued("1125823297", "Order Fulfilled", "Pending for Approver", Ems1165); + var buffer = new BlockingCollection(10); + + await plugin.Synchronize(buffer, null, true, CancellationToken.None); + + var record = buffer.ToArray().Should().ContainSingle().Subject; + record.Status.Should().Be((int)Keyfactor.PKI.Enums.EJBCA.EndEntityStatus.EXTERNALVALIDATION); + record.Certificate.Should().BeNullOrEmpty(); + mock.Verify(c => c.ResolveAndDownloadCertificateV2Async("1125823297", It.IsAny()), Times.Once, + "the download is still tried every pass, so a certificate that appears is picked up"); + capture.Lines(LogLevel.Information, "synchronization complete").Should().ContainSingle() + .Which.Should().Contain("GeneratedNoBody=0").And.Contain("Pending=1").And.Contain("IssuedNotGeneratedYet=1"); + } + + [Fact] + public async Task Sync_OrderFulfilledPendingForApprover_OtherDownloadFailure_StaysIssuedWithoutBody() + { + // A transient failure says nothing about the certificate; keep Track's issued. + var (_, plugin) = TrackIssued("1125823297", "Order Fulfilled", "Pending for Approver", + new System.Exception("CERTInext V2 API error during 'V2 download certificate'. HTTP 503.")); + var buffer = new BlockingCollection(10); + + await plugin.Synchronize(buffer, null, true, CancellationToken.None); + + buffer.ToArray().Should().ContainSingle().Which.Status.Should().Be((int)Keyfactor.PKI.Enums.EJBCA.EndEntityStatus.GENERATED); + } + + [Fact] + public async Task Sync_UnmappedPairTrackIssued_NotGenerated_StaysIssuedWithoutBody() + { + // The pending override applies only when the report itself says the certificate is pending. + var (_, plugin) = TrackIssued("b1", "Brand New", "Never Seen", Ems1165); + var buffer = new BlockingCollection(10); + + await plugin.Synchronize(buffer, null, true, CancellationToken.None); + + buffer.ToArray().Should().ContainSingle().Which.Status.Should().Be((int)Keyfactor.PKI.Enums.EJBCA.EndEntityStatus.GENERATED); + } } } diff --git a/CERTInext/CERTInextCAPlugin.cs b/CERTInext/CERTInextCAPlugin.cs index 02e1279..e92d66d 100644 --- a/CERTInext/CERTInextCAPlugin.cs +++ b/CERTInext/CERTInextCAPlugin.cs @@ -3795,7 +3795,23 @@ await TryAcceptV2AgreementAsync( } catch (Exception dlEx) { - if (IsCertificateNotGeneratedYet(dlEx)) + if (IsCertificateNotGeneratedYet(dlEx) && IsReportCertificatePending(row.CertificateStatus)) + { + // Track said issued only because the report row disagreed with itself + // ("Order Fulfilled | Pending for Approver"), and there is no certificate: + // the report's certificate status was right (live: 1125823297, placed + // months before the sandbox stopped generating, still EMS-1165). Emit it + // pending, as before the Track fallback; once a certificate exists the + // download succeeds and it is emitted issued. + issuedNotGeneratedYet++; + disposition = (int)EndEntityStatus.EXTERNALVALIDATION; + _logger.LogDebug( + "V2 sync: order '{Id}' is issued per Track Order but its certificate is not generated " + + "(Download Certificate 422 EMS-1165) and the report's certificate status is " + + "'{CertificateStatus}' — emitting it as pending. {States}", + row.OrderNumber, LogSanitizer.Strip(row.CertificateStatus), DescribeV2States(trackedStatus)); + } + else if (IsCertificateNotGeneratedYet(dlEx)) { // Not a failure: issued at the CA, certificate not generated yet. // Per-order line at Debug; the count is in the pass summary below. @@ -4067,6 +4083,10 @@ internal static bool ShouldDeferRecentOrder( return null; } + /// True when a report row's certificateStatus text maps to pending. + internal static bool IsReportCertificatePending(string certificateStatus) => + TryMapV2ReportDisplayStatus(certificateStatus, out int d) && d == (int)EndEntityStatus.EXTERNALVALIDATION; + private static bool TryMapV2ReportDisplayStatus(string status, out int disposition) { disposition = default; diff --git a/CHANGELOG.md b/CHANGELOG.md index a15d675..21f266f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -35,7 +35,7 @@ - fix(sync): The V2 sync summary lists every `orderStatus | certificateStatus` pair from `/reports/orders` that the plugin didn't recognize, with counts (`UnmappedReportStatuses=[...]`), at Information. CERTInext doesn't document these values, so new ones now show up in ordinary logs. - fix(enroll): New setting `EnrollmentCallBudgetSeconds` (default 50, `0` disables, at most 90). It bounds the in-call pickup wait by a deadline measured from the start of `Enroll`, so time spent creating or reissuing the order counts against it. Before, the 55 s default pickup started only after the create (a V2 reissue alone took about 26 s live), so Command failed the enrollment at its 60 s Workflow Step Run Timeout while the order went on at CERTInext. That invited a resubmit and a duplicate order. The pickup now shortens its waits, skips the delay after its last poll, and returns pending with one Information line when no further poll fits. Calls already in flight are never cut short, and `PickupRetries=0` still disables the pickup. Set it about 10 s below Command's Workflow Step Run Timeout if you raise that (V1 and V2). - fix(dcv): V2 DCV looks each domain up (`GET /domains`) once per sync pass, and once per `Enroll` or single-record call, instead of once per pending order and SAN. Found rows and "no row" are reused; a failed lookup is not, so the next order on that domain tries again. -- fix(sync): A V2 `/reports/orders` row that reads `Order Fulfilled | Pending for Approver` is resolved through Track Order, which returns `issued`, so the certificate is downloaded. It used to be reported as pending and never downloaded. Other disagreeing pairs, such as `Order Accepted | Certificate Revoked`, keep their mapping, because the certificate status is correct for them. +- fix(sync): A V2 `/reports/orders` row that reads `Order Fulfilled | Pending for Approver` is resolved through Track Order, which returns `issued`, and its certificate is downloaded when one exists. It used to be reported as pending without a download attempt. When the download answers 422 `EMS-1165` (certificate not generated), the order is still reported as pending, as its certificate status says. Other disagreeing pairs, such as `Order Accepted | Certificate Revoked`, keep their mapping, because the certificate status is correct for them. - fix(v2): A V2 OAuth2 token request that gets no HTTP response (a dropped connection or other transport error) is retried twice, after 1 s and 3 s, so one network blip no longer fails an enrollment, a sync or a connector save. HTTP errors (400/401/403) are not retried, and order creates are still never retried. Token failures and other V2 calls with no response now log the transport detail (`TransportDetail=`: RestSharp's response status and the exception types and messages, with credentials removed) and include a short form in the error, instead of only `HttpStatus=0`. - fix(sync): The V2 sync also holds back pending and issued orders created in the last 120 s (`SyncRecentOrderGraceSeconds`, `0` disables), so an in-flight enrollment no longer fails with a duplicate key (V1 since 1.0.1). - fix(enroll): The in-call pickup wait is now capped at 75 s (it was 180 s) for V1 and V2, inside Command's roughly 100 s enrollment-call timeout, so a pickup that used its whole budget is no longer abandoned by Command. The 55 s default (`PickupRetries` 5, `PickupDelay` 10) is unaffected. diff --git a/docsource/configuration.md b/docsource/configuration.md index 1a848d3..757f9c6 100644 --- a/docsource/configuration.md +++ b/docsource/configuration.md @@ -610,7 +610,7 @@ mapped to Failed — see the gateway trace log if certificates unexpectedly show **V2 synchronization:** - Synchronize pages through `/reports/orders`. Pages are capped at 100 rows, and `PageSize` is clamped to that. -- The report carries display strings (for example `Order Fulfilled`, `Certificate Downloaded`) rather than the status enum above. Recognized strings are mapped directly. Any other combination falls back to a live order-status call, so a new display value never silently misclassifies an order. If that call finds the order in no product family, as for every `On Hold | Setup Pending` row on the sandbox, the order is skipped for that pass and counted as `UntrackableListedOrders`; it isn't treated as an error. CERTInext doesn't document these display strings, so the sync summary names every pair it didn't recognize (`UnmappedReportStatuses=[...]`). Report a new pair so it can be mapped. One known pair is deliberately left unmapped: `Order Fulfilled | Pending for Approver` (the order fulfilled, the certificate still pending). Track Order returns `issued` for it, so the plugin asks Track Order and downloads the certificate instead of reporting the order as pending. +- The report carries display strings (for example `Order Fulfilled`, `Certificate Downloaded`) rather than the status enum above. Recognized strings are mapped directly. Any other combination falls back to a live order-status call, so a new display value never silently misclassifies an order. If that call finds the order in no product family, as for every `On Hold | Setup Pending` row on the sandbox, the order is skipped for that pass and counted as `UntrackableListedOrders`; it isn't treated as an error. CERTInext doesn't document these display strings, so the sync summary names every pair it didn't recognize (`UnmappedReportStatuses=[...]`). Report a new pair so it can be mapped. One known pair is deliberately left unmapped: `Order Fulfilled | Pending for Approver` (the order fulfilled, the certificate still pending). Track Order returns `issued` for it, so the plugin asks Track Order and tries to download the certificate. If CERTInext answers that the certificate isn't generated (422 `EMS-1165`), the order is reported as pending, as its certificate status says; seen live on an order whose certificate was never generated. The download is tried again on every sync, so the certificate is imported once it exists. - Cancelled and rejected orders are skipped. Issued orders have their certificate chain downloaded. - CERTInext does not serve the certificate body of a revoked order. A revoked order is propagated as revoked only when the gateway already holds that certificate (the revocation date and reason come from a live status call). - Otherwise a revoked order is reported as Failed (the gateway has a record without a body) or skipped (no record), so the gateway never stores a revoked record without a certificate. From f7d077510b15d6f04d70dd8fe4f4f672b48d7eb8 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" Date: Mon, 16 Nov 2026 16:38:49 +0000 Subject: [PATCH 07/11] docs: auto-generate README and documentation [skip ci] --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 28b6db7..ee356bc 100644 --- a/README.md +++ b/README.md @@ -660,7 +660,7 @@ mapped to Failed — see the gateway trace log if certificates unexpectedly show **V2 synchronization:** - Synchronize pages through `/reports/orders`. Pages are capped at 100 rows, and `PageSize` is clamped to that. -- The report carries display strings (for example `Order Fulfilled`, `Certificate Downloaded`) rather than the status enum above. Recognized strings are mapped directly. Any other combination falls back to a live order-status call, so a new display value never silently misclassifies an order. If that call finds the order in no product family, as for every `On Hold | Setup Pending` row on the sandbox, the order is skipped for that pass and counted as `UntrackableListedOrders`; it isn't treated as an error. CERTInext doesn't document these display strings, so the sync summary names every pair it didn't recognize (`UnmappedReportStatuses=[...]`). Report a new pair so it can be mapped. One known pair is deliberately left unmapped: `Order Fulfilled | Pending for Approver` (the order fulfilled, the certificate still pending). Track Order returns `issued` for it, so the plugin asks Track Order and downloads the certificate instead of reporting the order as pending. +- The report carries display strings (for example `Order Fulfilled`, `Certificate Downloaded`) rather than the status enum above. Recognized strings are mapped directly. Any other combination falls back to a live order-status call, so a new display value never silently misclassifies an order. If that call finds the order in no product family, as for every `On Hold | Setup Pending` row on the sandbox, the order is skipped for that pass and counted as `UntrackableListedOrders`; it isn't treated as an error. CERTInext doesn't document these display strings, so the sync summary names every pair it didn't recognize (`UnmappedReportStatuses=[...]`). Report a new pair so it can be mapped. One known pair is deliberately left unmapped: `Order Fulfilled | Pending for Approver` (the order fulfilled, the certificate still pending). Track Order returns `issued` for it, so the plugin asks Track Order and tries to download the certificate. If CERTInext answers that the certificate isn't generated (422 `EMS-1165`), the order is reported as pending, as its certificate status says; seen live on an order whose certificate was never generated. The download is tried again on every sync, so the certificate is imported once it exists. - Cancelled and rejected orders are skipped. Issued orders have their certificate chain downloaded. - CERTInext does not serve the certificate body of a revoked order. A revoked order is propagated as revoked only when the gateway already holds that certificate (the revocation date and reason come from a live status call). - Otherwise a revoked order is reported as Failed (the gateway has a record without a body) or skipped (no record), so the gateway never stores a revoked record without a certificate. From 3dd45f033eed550f52bffbc6765fd8683609285e Mon Sep 17 00:00:00 2001 From: spbsoluble <1661003+spbsoluble@users.noreply.github.com> Date: Mon, 16 Nov 2026 08:55:24 -0800 Subject: [PATCH 08/11] fix(v2): GetSingleRecord returns pending for an issued order with no certificate and a pending certificate state Matches the V2 sync rule: Track says issued, Download Certificate answers 422 EMS-1165, and the order's certificateState (same text as the report's certificateStatus: Pending for Approver, Approved by System, Order Accepted) maps to pending, so the record is pending rather than issued without a body. An unrecognized or non-pending state, and other download failures, keep the existing result. Docs no longer claim the plugin never acts on certificateState. --- .../V2CertificateNotGeneratedTests.cs | 41 ++++++++++++++++--- CERTInext/CERTInextCAPlugin.cs | 14 ++++++- CHANGELOG.md | 2 +- docsource/configuration.md | 6 +-- 4 files changed, 53 insertions(+), 10 deletions(-) diff --git a/CERTInext.Tests/V2CertificateNotGeneratedTests.cs b/CERTInext.Tests/V2CertificateNotGeneratedTests.cs index ff28910..90de5b4 100644 --- a/CERTInext.Tests/V2CertificateNotGeneratedTests.cs +++ b/CERTInext.Tests/V2CertificateNotGeneratedTests.cs @@ -179,13 +179,20 @@ public async Task Enroll_OtherDownloadErrors_StillWarnPerAttempt() // GetSingleRecord // --------------------------------------------------------------------------- - [Fact] - public async Task GetSingleRecord_IssuedButNotGenerated_LogsInfoNotWarning_AndReturnsTheRecordWithoutABody() + [Theory] + // The certificate state says pending (same text the report's certificateStatus uses): returned pending, + // matching the V2 sync. Live: 1125823297 ("Pending for Approver"); the sandbox's recent orders + // ("Approved by System"). + [InlineData("Approved by System")] + [InlineData("Pending for Approver")] + public async Task GetSingleRecord_IssuedButNotGenerated_CertificateStatePending_ReturnsPendingWithoutBody(string certificateState) { using var capture = new PluginLogCapture(); var mock = new Mock(MockBehavior.Strict); + var status = IssuedButNotGenerated(); + status.CertificateState = certificateState; mock.Setup(c => c.ResolveAndTrackOrderV2WithFamilyAsync(OrderId, It.IsAny())) - .ReturnsAsync((Constants.ApiV2.FamilySsl, IssuedButNotGenerated())); + .ReturnsAsync((Constants.ApiV2.FamilySsl, status)); mock.Setup(c => c.ResolveAndDownloadCertificateV2Async(OrderId, It.IsAny())) .ThrowsAsync(NotGenerated); var plugin = new CERTInextCAPlugin(mock.Object, Config()); @@ -194,10 +201,34 @@ public async Task GetSingleRecord_IssuedButNotGenerated_LogsInfoNotWarning_AndRe record.CARequestID.Should().Be(OrderId); record.Certificate.Should().BeNull(); + record.Status.Should().Be((int)EndEntityStatus.EXTERNALVALIDATION); capture.Entries.Where(e => e.Level >= LogLevel.Warning).Should().BeEmpty(); - var lines = capture.Lines(LogLevel.Information, "not generated yet"); + var lines = capture.Lines(LogLevel.Information, "returning it as pending"); lines.Should().ContainSingle(); - lines[0].Should().Contain("CertificateState='Approved by System'"); + lines[0].Should().Contain($"CertificateState='{certificateState}'"); + } + + [Theory] + [InlineData(null)] + [InlineData("Certificate Generated")] + [InlineData("Some New State")] + public async Task GetSingleRecord_IssuedButNotGenerated_CertificateStateNotPending_ReturnsIssuedWithoutBody(string certificateState) + { + using var capture = new PluginLogCapture(); + var mock = new Mock(MockBehavior.Strict); + var status = IssuedButNotGenerated(); + status.CertificateState = certificateState; + mock.Setup(c => c.ResolveAndTrackOrderV2WithFamilyAsync(OrderId, It.IsAny())) + .ReturnsAsync((Constants.ApiV2.FamilySsl, status)); + mock.Setup(c => c.ResolveAndDownloadCertificateV2Async(OrderId, It.IsAny())) + .ThrowsAsync(NotGenerated); + var plugin = new CERTInextCAPlugin(mock.Object, Config()); + + var record = await plugin.GetSingleRecord(OrderId); + + record.Status.Should().Be((int)EndEntityStatus.GENERATED); + record.Certificate.Should().BeNull(); + capture.Lines(LogLevel.Information, "not generated yet").Should().ContainSingle(); } [Fact] diff --git a/CERTInext/CERTInextCAPlugin.cs b/CERTInext/CERTInextCAPlugin.cs index e92d66d..075e24a 100644 --- a/CERTInext/CERTInextCAPlugin.cs +++ b/CERTInext/CERTInextCAPlugin.cs @@ -3415,7 +3415,19 @@ private async Task GetSingleRecordV2Async(string caReque } catch (Exception dlEx) { - if (IsCertificateNotGeneratedYet(dlEx)) + if (IsCertificateNotGeneratedYet(dlEx) && IsReportCertificatePending(statusResp.CertificateState)) + { + // Same rule as the V2 sync: Track says issued, there is no certificate, and the + // order's own certificate state (same text as the report's certificateStatus, + // e.g. "Pending for Approver", "Approved by System") says pending. Return pending + // rather than issued without a body (live: 1125823297). + disposition = (int)EndEntityStatus.EXTERNALVALIDATION; + _logger.LogInformation( + "V2 GetSingleRecord: order is issued per Track Order but its certificate is not generated " + + "(Download Certificate 422 EMS-1165) and its certificate state is pending; returning it " + + "as pending. CARequestID={Id}, {States}", caRequestID, DescribeV2States(statusResp)); + } + else if (IsCertificateNotGeneratedYet(dlEx)) { _logger.LogInformation( "V2 GetSingleRecord: order is issued at CERTInext but its certificate is not generated " + diff --git a/CHANGELOG.md b/CHANGELOG.md index 21f266f..ffcdc61 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -35,7 +35,7 @@ - fix(sync): The V2 sync summary lists every `orderStatus | certificateStatus` pair from `/reports/orders` that the plugin didn't recognize, with counts (`UnmappedReportStatuses=[...]`), at Information. CERTInext doesn't document these values, so new ones now show up in ordinary logs. - fix(enroll): New setting `EnrollmentCallBudgetSeconds` (default 50, `0` disables, at most 90). It bounds the in-call pickup wait by a deadline measured from the start of `Enroll`, so time spent creating or reissuing the order counts against it. Before, the 55 s default pickup started only after the create (a V2 reissue alone took about 26 s live), so Command failed the enrollment at its 60 s Workflow Step Run Timeout while the order went on at CERTInext. That invited a resubmit and a duplicate order. The pickup now shortens its waits, skips the delay after its last poll, and returns pending with one Information line when no further poll fits. Calls already in flight are never cut short, and `PickupRetries=0` still disables the pickup. Set it about 10 s below Command's Workflow Step Run Timeout if you raise that (V1 and V2). - fix(dcv): V2 DCV looks each domain up (`GET /domains`) once per sync pass, and once per `Enroll` or single-record call, instead of once per pending order and SAN. Found rows and "no row" are reused; a failed lookup is not, so the next order on that domain tries again. -- fix(sync): A V2 `/reports/orders` row that reads `Order Fulfilled | Pending for Approver` is resolved through Track Order, which returns `issued`, and its certificate is downloaded when one exists. It used to be reported as pending without a download attempt. When the download answers 422 `EMS-1165` (certificate not generated), the order is still reported as pending, as its certificate status says. Other disagreeing pairs, such as `Order Accepted | Certificate Revoked`, keep their mapping, because the certificate status is correct for them. +- fix(sync): A V2 `/reports/orders` row that reads `Order Fulfilled | Pending for Approver` is resolved through Track Order, which returns `issued`, and its certificate is downloaded when one exists. It used to be reported as pending without a download attempt. When the download answers 422 `EMS-1165` (certificate not generated), the order is still reported as pending, as its certificate status says. `GetSingleRecord` does the same, reading Track Order's `certificateState`: an issued order with no certificate and a pending certificate state (for example `Approved by System`, as on the sandbox's recent orders) is returned as pending, not as issued without a certificate. Other disagreeing pairs, such as `Order Accepted | Certificate Revoked`, keep their mapping, because the certificate status is correct for them. - fix(v2): A V2 OAuth2 token request that gets no HTTP response (a dropped connection or other transport error) is retried twice, after 1 s and 3 s, so one network blip no longer fails an enrollment, a sync or a connector save. HTTP errors (400/401/403) are not retried, and order creates are still never retried. Token failures and other V2 calls with no response now log the transport detail (`TransportDetail=`: RestSharp's response status and the exception types and messages, with credentials removed) and include a short form in the error, instead of only `HttpStatus=0`. - fix(sync): The V2 sync also holds back pending and issued orders created in the last 120 s (`SyncRecentOrderGraceSeconds`, `0` disables), so an in-flight enrollment no longer fails with a duplicate key (V1 since 1.0.1). - fix(enroll): The in-call pickup wait is now capped at 75 s (it was 180 s) for V1 and V2, inside Command's roughly 100 s enrollment-call timeout, so a pickup that used its whole budget is no longer abandoned by Command. The 55 s default (`PickupRetries` 5, `PickupDelay` 10) is unaffected. diff --git a/docsource/configuration.md b/docsource/configuration.md index 757f9c6..d72ed3a 100644 --- a/docsource/configuration.md +++ b/docsource/configuration.md @@ -615,7 +615,7 @@ mapped to Failed — see the gateway trace log if certificates unexpectedly show - CERTInext does not serve the certificate body of a revoked order. A revoked order is propagated as revoked only when the gateway already holds that certificate (the revocation date and reason come from a live status call). - Otherwise a revoked order is reported as Failed (the gateway has a record without a body) or skipped (no record), so the gateway never stores a revoked record without a certificate. - `IgnoreExpired` is applied here: expired certificates are skipped. -- An issued order whose download answers 422 `EMS-1165` is emitted without a certificate body and counted as `IssuedNotGeneratedYet` in the sync summary instead of logging a warning per order; a later pass picks it up. +- An issued order whose download answers 422 `EMS-1165` is counted as `IssuedNotGeneratedYet` in the sync summary instead of logging a warning per order. It is emitted as pending when the row's certificate status says pending, otherwise without a certificate body; a later pass picks it up. #### SSL.com organization validation @@ -644,8 +644,8 @@ The create body already carries the agreement (`signerName`, `signerPlace`, `acc CERTInext can report an order as `issued` before the certificate exists: Download Certificate then answers HTTP 422 `EMS-1165 Invalid request status.` Normally the certificate is generated about 20 seconds later, but the sandbox has been seen to take far longer. The plugin treats this as an expected state, not an error: - **Enrollment:** the pickup poll keeps waiting (within `PickupRetries` x `PickupDelay`), logging each attempt at Debug level and writing one Information summary if the budget runs out. The enrollment returns pending, and a later synchronization imports the certificate. -- **`GetSingleRecord` and Synchronize:** logged at Information (single record) or Debug with a count in the sync summary, rather than a warning. The record is returned without a certificate body, as for any failed download. -- **Log fields:** the lines include CERTInext's `orderState` and `certificateState` text (for example `Approved by System` versus `Certificate Generated`) for diagnosis. Their vocabulary isn't documented, so the plugin never acts on it. +- **`GetSingleRecord` and Synchronize:** logged at Information (single record) or Debug with a count in the sync summary, rather than a warning. When the order's certificate status says pending (`Pending for Approver`, `Approved by System` or `Order Accepted`), the record is returned as **pending**. `GetSingleRecord` reads that status from Track Order's `certificateState`, and the sync from the report's `certificateStatus`, which use the same text. Otherwise the record is returned as issued without a certificate body, as for any failed download. A later pass downloads the certificate once it exists. +- **Log fields:** the lines include CERTInext's `orderState` and `certificateState` text (for example `Approved by System` versus `Certificate Generated`) for diagnosis. Their vocabulary isn't documented, so the plugin acts on it only in the case above, and only to report pending rather than issued; an unrecognized value keeps the issued-without-body result. - **Any other download error** is still logged as a warning. #### V2 reissue From fcdb49d9fc0427fde293620e2bc5f4573e395a56 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" Date: Mon, 16 Nov 2026 16:55:55 +0000 Subject: [PATCH 09/11] docs: auto-generate README and documentation [skip ci] --- README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index ee356bc..ea06c4e 100644 --- a/README.md +++ b/README.md @@ -665,7 +665,7 @@ mapped to Failed — see the gateway trace log if certificates unexpectedly show - CERTInext does not serve the certificate body of a revoked order. A revoked order is propagated as revoked only when the gateway already holds that certificate (the revocation date and reason come from a live status call). - Otherwise a revoked order is reported as Failed (the gateway has a record without a body) or skipped (no record), so the gateway never stores a revoked record without a certificate. - `IgnoreExpired` is applied here: expired certificates are skipped. -- An issued order whose download answers 422 `EMS-1165` is emitted without a certificate body and counted as `IssuedNotGeneratedYet` in the sync summary instead of logging a warning per order; a later pass picks it up. +- An issued order whose download answers 422 `EMS-1165` is counted as `IssuedNotGeneratedYet` in the sync summary instead of logging a warning per order. It is emitted as pending when the row's certificate status says pending, otherwise without a certificate body; a later pass picks it up. #### SSL.com organization validation @@ -694,8 +694,8 @@ The create body already carries the agreement (`signerName`, `signerPlace`, `acc CERTInext can report an order as `issued` before the certificate exists: Download Certificate then answers HTTP 422 `EMS-1165 Invalid request status.` Normally the certificate is generated about 20 seconds later, but the sandbox has been seen to take far longer. The plugin treats this as an expected state, not an error: - **Enrollment:** the pickup poll keeps waiting (within `PickupRetries` x `PickupDelay`), logging each attempt at Debug level and writing one Information summary if the budget runs out. The enrollment returns pending, and a later synchronization imports the certificate. -- **`GetSingleRecord` and Synchronize:** logged at Information (single record) or Debug with a count in the sync summary, rather than a warning. The record is returned without a certificate body, as for any failed download. -- **Log fields:** the lines include CERTInext's `orderState` and `certificateState` text (for example `Approved by System` versus `Certificate Generated`) for diagnosis. Their vocabulary isn't documented, so the plugin never acts on it. +- **`GetSingleRecord` and Synchronize:** logged at Information (single record) or Debug with a count in the sync summary, rather than a warning. When the order's certificate status says pending (`Pending for Approver`, `Approved by System` or `Order Accepted`), the record is returned as **pending**. `GetSingleRecord` reads that status from Track Order's `certificateState`, and the sync from the report's `certificateStatus`, which use the same text. Otherwise the record is returned as issued without a certificate body, as for any failed download. A later pass downloads the certificate once it exists. +- **Log fields:** the lines include CERTInext's `orderState` and `certificateState` text (for example `Approved by System` versus `Certificate Generated`) for diagnosis. Their vocabulary isn't documented, so the plugin acts on it only in the case above, and only to report pending rather than issued; an unrecognized value keeps the issued-without-body result. - **Any other download error** is still logged as a warning. #### V2 reissue From 410d3051261840268adcbc59b6d8011988cbef37 Mon Sep 17 00:00:00 2001 From: spbsoluble <1661003+spbsoluble@users.noreply.github.com> Date: Mon, 16 Nov 2026 09:03:27 -0800 Subject: [PATCH 10/11] test(live): GetSingleRecord returns pending for issued orders with no certificate and a pending state Opt-in with CERTINEXT_V2_FULFILLED_PENDING_SYNC=1, read-only, DCV off; orders from CERTINEXT_V2_SINGLE_RECORD_ORDERS. Also relaxes nothing in the sync test, which now expects pending without a body. Live 2026-11-16: 1125823297 (Pending for Approver) and 6292373831 (Approved by System) both returned pending (90); the one-order sync emitted 1125823297 pending. --- .../V2FulfilledPendingSyncLiveTests.cs | 47 +++++++++++++++++++ 1 file changed, 47 insertions(+) diff --git a/CERTInext.IntegrationTests/V2FulfilledPendingSyncLiveTests.cs b/CERTInext.IntegrationTests/V2FulfilledPendingSyncLiveTests.cs index ca5b8f0..0486d2b 100644 --- a/CERTInext.IntegrationTests/V2FulfilledPendingSyncLiveTests.cs +++ b/CERTInext.IntegrationTests/V2FulfilledPendingSyncLiveTests.cs @@ -149,5 +149,52 @@ public async Task Sync_OrderFulfilledPendingForApprover_TracksAndDownloads() restoreLogging(); } } + + /// + /// The same rule through GetSingleRecord, which reads Track Order's certificateState + /// instead of the report. Read-only, DCV off. Orders from CERTINEXT_V2_SINGLE_RECORD_ORDERS + /// (comma-separated; default 1125823297). For each: issued with a certificate, or pending without one + /// when the certificate state says pending. + /// + [SkippableFact] + public async Task GetSingleRecord_IssuedWithoutCertificate_PendingCertificateState_ReturnsPending() + { + string apiUrl = V2EnvHelper.GetEnv(_env, "CERTINEXT_API_URL"); + string clientId = V2EnvHelper.GetEnv(_env, "CERTINEXT_CLIENT_ID"); + string clientSecret = V2EnvHelper.GetEnv(_env, "CERTINEXT_CLIENT_SECRET"); + Skip.If(string.IsNullOrWhiteSpace(V2EnvHelper.GetEnv(_env, "CERTINEXT_USE_V2_API")) + || string.IsNullOrWhiteSpace(apiUrl) || string.IsNullOrWhiteSpace(clientId) + || string.IsNullOrWhiteSpace(clientSecret) + || V2EnvHelper.GetEnv(_env, "CERTINEXT_V2_FULFILLED_PENDING_SYNC") != "1", + "Requires CERTINEXT_USE_V2_API + V2 credentials and CERTINEXT_V2_FULFILLED_PENDING_SYNC=1."); + var orderIds = V2EnvHelper.GetEnv(_env, "CERTINEXT_V2_SINGLE_RECORD_ORDERS", "1125823297") + .Split(',', StringSplitOptions.RemoveEmptyEntries | StringSplitOptions.TrimEntries); + + var config = new CERTInextConfig + { + ApiUrl = apiUrl, UseV2Api = true, OAuthClientId = clientId, OAuthClientSecret = clientSecret, + SignerPlace = "Gateway Lab", DcvEnabled = false + }; + var restoreLogging = TestOutputLogging.RouteTo(_output); + try + { + using var plugin = new CERTInextCAPlugin(new CERTInextClient(config), config); + foreach (string id in orderIds) + { + var record = await plugin.GetSingleRecord(id); + bool hasBody = !string.IsNullOrWhiteSpace(record.Certificate); + _output.WriteLine($"GetSingleRecord {id}: Status={record.Status}, HasCertificate={hasBody}, ProductID={record.ProductID}"); + if (hasBody) + record.Status.Should().Be((int)EndEntityStatus.GENERATED, $"order {id} has a certificate"); + else + record.Status.Should().NotBe((int)EndEntityStatus.GENERATED, + $"order {id} has no certificate; a pending certificate state must be reported pending"); + } + } + finally + { + restoreLogging(); + } + } } } From ed2ceba89096442fe74b04716579ade985ae53db Mon Sep 17 00:00:00 2001 From: spbsoluble <1661003+spbsoluble@users.noreply.github.com> Date: Mon, 16 Nov 2026 09:37:49 -0800 Subject: [PATCH 11/11] docs(v2): CertificateState comment reflects its one use in GetSingleRecord --- CERTInext/API/V2/CertificateResponseV2.cs | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/CERTInext/API/V2/CertificateResponseV2.cs b/CERTInext/API/V2/CertificateResponseV2.cs index d01631a..a68460b 100644 --- a/CERTInext/API/V2/CertificateResponseV2.cs +++ b/CERTInext/API/V2/CertificateResponseV2.cs @@ -147,10 +147,11 @@ public class V2OrderStatusResponse /// /// CERTInext's free-text certificate state (live values seen: "Approved by System", - /// "Certificate Generated", "System Error"). Undocumented vocabulary: for diagnostics and - /// log lines only, never branch logic on it. Notably an order can report - /// "issued" while this still reads "Approved by System" and the - /// certificate cannot be downloaded yet (Download Certificate answers 422 EMS-1165). + /// "Certificate Generated", "System Error", "Pending for Approver"). Undocumented vocabulary, + /// used for diagnostics and log lines, plus one decision: GetSingleRecord returns an + /// order pending when is "issued", Download Certificate answers 422 + /// EMS-1165, and this value maps to pending (same text as the report's certificateStatus). + /// Notably an order can report "issued" while this still reads "Approved by System". /// [JsonPropertyName("certificateState")] public string CertificateState { get; set; }