Add preferred chain selection via RFC 8555 §7.4.2 alternate links

Author: bashgeek

README.md

@@ -126,6 +126,7 @@ echo $cert->caBundle;    // PEM intermediate chain
 - [Automatic renewal](#automatic-renewal)
 - [ARI: CA-guided renewal windows](#ari-ca-guided-renewal-windows)
 - [ACME profiles](#acme-profiles)
+- [Preferred chain selection](#preferred-chain-selection)
 - [Key types](#key-types)
 - [Certificate revocation](#certificate-revocation)
 - [PSR-18 HTTP client](#psr-18-http-client)
@@ -701,6 +702,31 @@ Profiles are forwarded to the CA only if the provider reports `supportsProfiles(
 
 ---
 
+## Preferred chain selection
+
+Some CAs offer multiple certificate chains via `Link: rel="alternate"` headers (RFC 8555 §7.4.2). Let's Encrypt uses this to serve both the ISRG Root X1 chain and older cross-signed chains.
+
+Use `->preferredChain()` to request a specific chain by matching against the Common Name or Organisation of the intermediate certificates. The match is a case-insensitive substring, so partial names work fine.
+
+```php
+// Prefer the ISRG Root X1 chain (shorter, no DST cross-signature)
+CoyoteCert::with(new LetsEncrypt())
+    ->identifiers('example.com')
+    ->challenge(new Http01Handler('/var/www/html'))
+    ->preferredChain('ISRG Root X1')
+    ->issueOrRenew();
+```
+
+If no alternate chain matches, CoyoteCert falls back to the default chain returned by the CA — so this call is always safe to include even when the CA offers only one chain.
+
+When using the low-level API directly, pass the preference as a second argument to `getBundle()`:
+
+```php
+$bundle = $api->certificate()->getBundle($order, 'ISRG Root X1');
+```
+
+---
+
 ## Key types
 
 ```php
@@ -892,6 +918,7 @@ CoyoteCert::with(AcmeProviderInterface $provider)  // factory — select the CA
 | `->httpClient(ClientInterface, ...)` | fluent | built-in curl | PSR-18 HTTP client |
 | `->withHttpTimeout(int)` | fluent | `10` | Curl timeout in seconds |
 | `->logger(LoggerInterface)` | fluent | none | PSR-3 logger |
+| `->preferredChain(string)` | fluent | `''` | Preferred chain issuer CN/O (RFC 8555 §7.4.2); falls back to default chain if no match |
 | `->skipLocalTest()` | fluent | off | Disable pre-flight HTTP/DNS self-check |
 | `->skipCaaCheck()` | fluent | off | Disable CAA DNS pre-check (internal CAs, split-horizon DNS) |
 | `->issue()` | terminal | — | Issue unconditionally; returns `StoredCertificate` |

src/CoyoteCert.php

@@ -57,6 +57,7 @@ class CoyoteCert
     private KeyType                    $accountKeyType   = KeyType::EC_P256;
     private bool                       $localTest        = true;
     private bool                       $skipCaaCheck     = false;
+    private string                     $preferredChain   = '';
 
     private function __construct(private readonly AcmeProviderInterface $provider) {}
 
@@ -180,6 +181,23 @@ public function skipCaaCheck(): self
         return $this;
     }
 
+    /**
+     * Prefer a specific certificate chain by matching the issuer Common Name or
+     * Organisation of the intermediate certificates (RFC 8555 §7.4.2).
+     *
+     * When the CA offers alternate chains via Link: rel="alternate" headers, the
+     * first chain whose intermediates contain $issuer (case-insensitive substring)
+     * is returned. Falls back to the default chain when no match is found.
+     *
+     * Example: ->preferredChain('ISRG Root X1')
+     */
+    public function preferredChain(string $issuer): self
+    {
+        $this->preferredChain = $issuer;
+
+        return $this;
+    }
+
     /**
      * Set the HTTP timeout in seconds for the built-in curl client.
      * No-op when a custom PSR-18 client is configured.
@@ -335,7 +353,7 @@ private function fetchAndStoreCertificate(
         }
 
         $order  = $api->order()->waitUntilValid($order);
-        $bundle = $api->certificate()->getBundle($order);
+        $bundle = $api->certificate()->getBundle($order, $this->preferredChain ?: null);
 
         $parsed    = openssl_x509_parse($bundle->certificate);
         $expiresAt = isset($parsed['validTo_time_t'])

src/Endpoints/Certificate.php

@@ -9,7 +9,7 @@
 
 class Certificate extends Endpoint
 {
-    public function getBundle(OrderData $orderData): CertificateBundleData
+    public function getBundle(OrderData $orderData, ?string $preferredChain = null): CertificateBundleData
     {
         if ($orderData->certificateUrl === null) {
             throw new AcmeException('Order does not have a certificate URL yet.');
@@ -23,7 +23,71 @@ public function getBundle(OrderData $orderData): CertificateBundleData
             throw new AcmeException('Failed to fetch certificate.');
         }
 
-        return CertificateBundleData::fromResponse($response);
+        $primary = CertificateBundleData::fromResponse($response);
+
+        if ($preferredChain === null) {
+            return $primary;
+        }
+
+        $linkHeader = $response->getHeader('link', '');
+        $linkHeader = is_string($linkHeader) ? $linkHeader : '';
+
+        foreach ($this->parseAlternateLinks($linkHeader) as $url) {
+            $altResponse = $this->postSigned($url, $orderData->accountUrl);
+
+            if ($altResponse->getHttpResponseCode() !== 200) {
+                continue;
+            }
+
+            $candidate = CertificateBundleData::fromResponse($altResponse);
+
+            if ($this->chainMatchesIssuer($candidate, $preferredChain)) {
+                return $candidate;
+            }
+        }
+
+        return $primary;
+    }
+
+    /** @return string[] */
+    private function parseAlternateLinks(string $linkHeader): array
+    {
+        if ($linkHeader === '') {
+            return [];
+        }
+
+        $urls = [];
+
+        foreach (explode(',', $linkHeader) as $entry) {
+            if (preg_match('~<([^>]+)>\s*;\s*rel\s*=\s*["\']?alternate["\']?~i', trim($entry), $m)) {
+                $urls[] = $m[1];
+            }
+        }
+
+        return $urls;
+    }
+
+    private function chainMatchesIssuer(CertificateBundleData $bundle, string $preferredChain): bool
+    {
+        if ($bundle->caBundle === '') {
+            return false;
+        }
+
+        if (!preg_match_all('~(-----BEGIN CERTIFICATE-----[\s\S]+?-----END CERTIFICATE-----)~i', $bundle->caBundle, $matches)) {
+            return false;
+        }
+
+        foreach ($matches[1] as $certPem) {
+            $parsed = openssl_x509_parse($certPem);
+            $cn     = $parsed['subject']['CN'] ?? '';
+            $o      = $parsed['subject']['O']  ?? '';
+
+            if (stripos($cn, $preferredChain) !== false || stripos($o, $preferredChain) !== false) {
+                return true;
+            }
+        }
+
+        return false;
     }
 
     public function revoke(string $pem, int $reason = 0): bool

src/Http/Client.php

@@ -164,7 +164,16 @@ private function parseRawHeaders(string $rawHeaders): array
 
             [$name, $value] = explode(':', $header, 2);
 
-            $headersArr[str_replace('_', '-', strtolower($name))] = trim($value);
+            $key          = str_replace('_', '-', strtolower($name));
+            $trimmedValue = trim($value);
+
+            // Accumulate repeated headers (e.g. multiple Link: rel="alternate")
+            // as comma-separated, consistent with PSR-7 multi-value behaviour.
+            if (isset($headersArr[$key])) {
+                $headersArr[$key] .= ', ' . $trimmedValue;
+            } else {
+                $headersArr[$key] = $trimmedValue;
+            }
         }
 
         return $headersArr;

tests/Unit/Endpoints/EndpointsTest.php

@@ -1375,6 +1375,144 @@ function directoryBodyWithKeyChange(bool $withRenewalInfo = false): array
     expect($callCount)->toBe(2); // pending → valid after one retry
 });
 
+// ── Certificate::getBundle() preferred chain selection ────────────────────────
+
+function makeCertBundle(string $issuerCN = 'Test Issuer CA'): string
+{
+    $issuerKey  = openssl_pkey_new(['private_key_type' => OPENSSL_KEYTYPE_RSA, 'private_key_bits' => 2048]);
+    $issuerCsr  = openssl_csr_new(['commonName' => $issuerCN], $issuerKey);
+    $issuerCert = openssl_csr_sign($issuerCsr, null, $issuerKey, 3650, serial: 2);
+    openssl_x509_export($issuerCert, $issuerPem);
+
+    $leafKey  = openssl_pkey_new(['private_key_type' => OPENSSL_KEYTYPE_RSA, 'private_key_bits' => 2048]);
+    $leafCsr  = openssl_csr_new(['commonName' => 'leaf.example.com'], $leafKey);
+    $leafCert = openssl_csr_sign($leafCsr, $issuerCert, $issuerKey, 365, serial: 3);
+    openssl_x509_export($leafCert, $leafPem);
+
+    return $leafPem . "\n" . $issuerPem;
+}
+
+function certOrderData(): OrderData
+{
+    return new OrderData(
+        id: '1',
+        url: 'https://acme.example/order/1',
+        status: 'valid',
+        expires: '2099-01-01T00:00:00Z',
+        identifiers: [],
+        domainValidationUrls: [],
+        finalizeUrl: 'https://acme.example/finalize/1',
+        accountUrl: 'https://acme.example/account/1',
+        certificateUrl: 'https://acme.example/cert/1',
+        finalized: true,
+    );
+}
+
+it('Certificate::getBundle() returns preferred alternate chain when issuer CN matches', function () {
+    $storage         = withKeyStorage();
+    $primaryBundle   = makeCertBundle('Default Root CA');
+    $alternateBundle = makeCertBundle('ISRG Root X1');
+
+    $mock = closureMock(
+        getHandler: fn($url) => new Response([], $url, 200, directoryBody()),
+        postHandler: function ($url) use ($primaryBundle, $alternateBundle) {
+            if (str_contains($url, '/alt')) {
+                return new Response([], $url, 200, $alternateBundle);
+            }
+
+            return new Response(
+                ['link' => '<https://acme.example/cert/1/alt>;rel="alternate"'],
+                $url,
+                200,
+                $primaryBundle,
+            );
+        },
+    );
+
+    $bundle = makeEndpointApi($mock, $storage)->certificate()->getBundle(certOrderData(), 'ISRG Root X1');
+
+    preg_match_all('~(-----BEGIN CERTIFICATE-----[\s\S]+?-----END CERTIFICATE-----)~i', $bundle->caBundle, $m);
+    $parsed = openssl_x509_parse($m[1][0]);
+    expect($parsed['subject']['CN'])->toBe('ISRG Root X1');
+});
+
+it('Certificate::getBundle() falls back to primary when no alternate chain matches preferred issuer', function () {
+    $storage         = withKeyStorage();
+    $primaryBundle   = makeCertBundle('Default Root CA');
+    $alternateBundle = makeCertBundle('Some Other CA');
+
+    $mock = closureMock(
+        getHandler: fn($url) => new Response([], $url, 200, directoryBody()),
+        postHandler: function ($url) use ($primaryBundle, $alternateBundle) {
+            if (str_contains($url, '/alt')) {
+                return new Response([], $url, 200, $alternateBundle);
+            }
+
+            return new Response(
+                ['link' => '<https://acme.example/cert/1/alt>;rel="alternate"'],
+                $url,
+                200,
+                $primaryBundle,
+            );
+        },
+    );
+
+    $bundle = makeEndpointApi($mock, $storage)->certificate()->getBundle(certOrderData(), 'ISRG Root X1');
+
+    preg_match_all('~(-----BEGIN CERTIFICATE-----[\s\S]+?-----END CERTIFICATE-----)~i', $bundle->caBundle, $m);
+    $parsed = openssl_x509_parse($m[1][0]);
+    expect($parsed['subject']['CN'])->toBe('Default Root CA');
+});
+
+it('Certificate::getBundle() returns primary chain when no Link header is present with preferredChain set', function () {
+    $storage       = withKeyStorage();
+    $primaryBundle = makeCertBundle('Default Root CA');
+
+    $mock = closureMock(
+        getHandler: fn($url) => new Response([], $url, 200, directoryBody()),
+        postHandler: fn($url) => new Response([], $url, 200, $primaryBundle),
+    );
+
+    $bundle = makeEndpointApi($mock, $storage)->certificate()->getBundle(certOrderData(), 'ISRG Root X1');
+
+    preg_match_all('~(-----BEGIN CERTIFICATE-----[\s\S]+?-----END CERTIFICATE-----)~i', $bundle->caBundle, $m);
+    $parsed = openssl_x509_parse($m[1][0]);
+    expect($parsed['subject']['CN'])->toBe('Default Root CA');
+});
+
+it('Certificate::getBundle() handles multiple Link headers (comma-separated) and selects matching chain', function () {
+    $storage          = withKeyStorage();
+    $primaryBundle    = makeCertBundle('Default Root CA');
+    $alternate1Bundle = makeCertBundle('Other CA');
+    $alternate2Bundle = makeCertBundle('ISRG Root X1');
+
+    $mock = closureMock(
+        getHandler: fn($url) => new Response([], $url, 200, directoryBody()),
+        postHandler: function ($url) use ($primaryBundle, $alternate1Bundle, $alternate2Bundle) {
+            if (str_contains($url, '/alt2')) {
+                return new Response([], $url, 200, $alternate2Bundle);
+            }
+
+            if (str_contains($url, '/alt1')) {
+                return new Response([], $url, 200, $alternate1Bundle);
+            }
+
+            return new Response(
+                ['link' => '<https://acme.example/cert/1/alt1>;rel="alternate", <https://acme.example/cert/1/alt2>;rel="alternate"'],
+                $url,
+                200,
+                $primaryBundle,
+            );
+        },
+    );
+
+    $bundle = makeEndpointApi($mock, $storage)->certificate()->getBundle(certOrderData(), 'ISRG Root X1');
+
+    preg_match_all('~(-----BEGIN CERTIFICATE-----[\s\S]+?-----END CERTIFICATE-----)~i', $bundle->caBundle, $m);
+    $parsed = openssl_x509_parse($m[1][0]);
+    expect($parsed['subject']['CN'])->toBe('ISRG Root X1');
+});
+
 // ── Certificate::getBundle() null certificateUrl path (line 15) ──────────────
 
 it('Certificate::getBundle() throws AcmeException when certificateUrl is null', function () {