Merge pull request #5 from blendbyte/preferred-chain-selection

Add preferred chain selection (RFC 8555 §7.4.2)

Author: bashgeek

README.md

@@ -131,6 +131,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)
@@ -820,6 +821,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
@@ -1011,6 +1037,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) |
 | `->onIssued(callable)` | fluent | none | Callback fired after every successful issuance; receives `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   = '';
     /** @var callable[] */
     private array $onIssuedCallbacks = [];
     /** @var callable[] */
@@ -184,6 +185,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;
+    }
+
     /**
      * Register a callback invoked after every successful certificate issuance.
      * The callback receives the issued StoredCertificate as its sole argument.
@@ -367,7 +385,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/CoyoteCertTest.php

@@ -80,6 +80,11 @@ public function cleanup(string $d, string $tok): void {}
     expect($c->skipCaaCheck())->toBe($c);
 });
 
+it('preferredChain() returns self (fluent)', function () {
+    $c = makeCoyote();
+    expect($c->preferredChain('ISRG Root X1'))->toBe($c);
+});
+
 it('profile() returns self (fluent)', function () {
     $c = makeCoyote();
     expect($c->profile('shortlived'))->toBe($c);