Phase 1: ECDSA JWS, EAB, order polling, ARI support

bashgeek · bashgeek · commit 2dbeea8d0be8 · 2026-04-16T13:43:46.000+08:00
- JsonWebKey/JsonWebSignature/KeyId: add EC key support (ES256/ES384),
  fix DER→raw signature conversion for JOSE compliance
- Account: add EAB outer JWS for ZeroSSL/GTS/SSL.com; fix detail typo (RFC 8555)
- Order: add waitUntilValid() to poll processing→valid before cert download
- CoyoteCert: wire email builder, order poll, and ARI renewal window check
- Directory/RenewalInfo/RenewalWindow: RFC 9773 ARI endpoint with graceful fallback
diff --git a/src/Api.php b/src/Api.php
@@ -5,6 +5,7 @@
 use Psr\Log\LoggerInterface;
 use CoyoteCert\Endpoints\Account;
 use CoyoteCert\Endpoints\Certificate;
+use CoyoteCert\Endpoints\RenewalInfo;
 use CoyoteCert\Endpoints\Directory;
 use CoyoteCert\Endpoints\DomainValidation;
 use CoyoteCert\Endpoints\Nonce;
@@ -75,6 +76,11 @@ public function certificate(): Certificate
         return new Certificate($this);
     }
 
+    public function renewalInfo(): RenewalInfo
+    {
+        return new RenewalInfo($this);
+    }
+
     public function getHttpClient(): HttpClientInterface
     {
         if ($this->httpClient === null) {
diff --git a/src/CoyoteCert.php b/src/CoyoteCert.php
@@ -6,6 +6,7 @@
 use Psr\Log\LoggerInterface;
 use CoyoteCert\Enums\AuthorizationChallengeEnum;
 use CoyoteCert\Enums\KeyType;
+use CoyoteCert\DTO\RenewalWindow;
 use CoyoteCert\Exceptions\LetsEncryptClientException;
 use CoyoteCert\Interfaces\ChallengeHandlerInterface;
 use CoyoteCert\Provider\AcmeProviderInterface;
@@ -34,13 +35,14 @@
  */
 class CoyoteCert
 {
-    private ?StorageInterface       $storage         = null;
-    private ?LoggerInterface        $logger          = null;
-    private array                   $domains         = [];
+    private ?StorageInterface          $storage          = null;
+    private ?LoggerInterface           $logger           = null;
+    private string                     $email            = '';
+    private array                      $domains          = [];
     private ?ChallengeHandlerInterface $challengeHandler = null;
-    private KeyType                 $certKeyType     = KeyType::EC_P256;
-    private KeyType                 $accountKeyType  = KeyType::RSA_2048;
-    private bool                    $localTest       = true;
+    private KeyType                    $certKeyType      = KeyType::EC_P256;
+    private KeyType                    $accountKeyType   = KeyType::RSA_2048;
+    private bool                       $localTest        = true;
 
     private function __construct(private readonly AcmeProviderInterface $provider)
     {
@@ -53,6 +55,13 @@ public static function with(AcmeProviderInterface $provider): self
         return new self($provider);
     }
 
+    public function email(string $email): self
+    {
+        $this->email = $email;
+
+        return $this;
+    }
+
     public function storage(StorageInterface $storage): self
     {
         $this->storage = $storage;
@@ -126,7 +135,17 @@ public function needsRenewal(int $daysBeforeExpiry = 30): bool
 
         $cert = $this->storage->getCertificate($this->domains[0]);
 
-        return $cert === null || $cert->remainingDays() <= $daysBeforeExpiry;
+        if ($cert === null) {
+            return true;
+        }
+
+        $window = $this->ariWindow($cert);
+
+        if ($window !== null) {
+            return $window->isOpen();
+        }
+
+        return $cert->remainingDays() <= $daysBeforeExpiry;
     }
 
     // ── Terminal actions ──────────────────────────────────────────────────────
@@ -148,7 +167,7 @@ public function issue(): StoredCertificate
         // ── 1. Get or create ACME account ──────────────────────────────────
         $account = $api->account()->exists()
             ? $api->account()->get()
-            : $api->account()->create();
+            : $api->account()->create($this->email);
 
         // ── 2. Create order ────────────────────────────────────────────────
         $order = $api->order()->new($account, $this->domains);
@@ -200,16 +219,19 @@ public function issue(): StoredCertificate
             throw new LetsEncryptClientException('Order finalization failed.');
         }
 
-        // ── 13. Download certificate bundle ───────────────────────────────
+        // ── 13. Poll until order transitions processing → valid ────────────
+        $order = $api->order()->waitUntilValid($order);
+
+        // ── 14. Download certificate bundle ───────────────────────────────
         $bundle = $api->certificate()->getBundle($order);
 
-        // ── 14. Parse expiry date from the DER-encoded certificate ─────────
+        // ── 15. Parse expiry date from the DER-encoded certificate ─────────
         $parsed    = openssl_x509_parse($bundle->certificate);
         $expiresAt = isset($parsed['validTo_time_t'])
             ? (new DateTimeImmutable())->setTimestamp((int) $parsed['validTo_time_t'])
             : new DateTimeImmutable('+90 days');
 
-        // ── 15. Build and persist the stored certificate ───────────────────
+        // ── 16. Build and persist the stored certificate ───────────────────
         $stored = new StoredCertificate(
             certificate: $bundle->certificate,
             privateKey:  $certKeyPem,
@@ -252,6 +274,25 @@ public function issueOrRenew(int $daysBeforeExpiry = 30): StoredCertificate
 
     // ── Private helpers ───────────────────────────────────────────────────────
 
+    private function ariWindow(StoredCertificate $cert): ?RenewalWindow
+    {
+        if (empty($cert->caBundle)) {
+            return null;
+        }
+
+        if (!preg_match('~(-----BEGIN CERTIFICATE-----[\s\S]+?-----END CERTIFICATE-----)~', $cert->caBundle, $m)) {
+            return null;
+        }
+
+        try {
+            return (new Api(provider: $this->provider, logger: $this->logger))
+                ->renewalInfo()
+                ->get($cert->certificate, $m[1]);
+        } catch (\Throwable) {
+            return null;
+        }
+    }
+
     private function validate(): void
     {
         if (empty($this->domains)) {
diff --git a/src/DTO/RenewalWindow.php b/src/DTO/RenewalWindow.php
@@ -0,0 +1,22 @@
+<?php
+
+namespace CoyoteCert\DTO;
+
+use DateTimeImmutable;
+
+readonly class RenewalWindow
+{
+    public function __construct(
+        public DateTimeImmutable $start,
+        public DateTimeImmutable $end,
+        public ?string           $explanationUrl = null,
+    ) {
+    }
+
+    public function isOpen(): bool
+    {
+        $now = new DateTimeImmutable();
+
+        return $now >= $this->start && $now <= $this->end;
+    }
+}
diff --git a/src/Endpoints/Account.php b/src/Endpoints/Account.php
@@ -3,8 +3,11 @@
 namespace CoyoteCert\Endpoints;
 
 use CoyoteCert\DTO\AccountData;
+use CoyoteCert\DTO\EabCredentials;
 use CoyoteCert\Exceptions\LetsEncryptClientException;
 use CoyoteCert\Http\Response;
+use CoyoteCert\Support\Base64;
+use CoyoteCert\Support\JsonWebKey;
 use CoyoteCert\Support\JsonWebSignature;
 
 class Account extends Endpoint
@@ -14,13 +17,31 @@ public function exists(): bool
         return $this->client->localAccount()->exists();
     }
 
-    public function create(): AccountData
+    public function create(string $email = ''): AccountData
     {
         $this->client->localAccount()->generateNewKeys();
 
-        $payload = [
-            'termsOfServiceAgreed' => true,
-        ];
+        $payload = ['termsOfServiceAgreed' => true];
+
+        if ($this->client->getProvider()->isEabRequired()) {
+            $eab = $this->client->getProvider()->getEabCredentials($email);
+
+            if ($eab === null) {
+                throw new LetsEncryptClientException(sprintf(
+                    '%s requires EAB credentials. Pass your EAB key ID and HMAC key when constructing the provider.',
+                    $this->client->getProvider()->getDisplayName()
+                ));
+            }
+
+            $accountKey    = $this->client->localAccount()->getPrivateKey();
+            $newAccountUrl = $this->client->directory()->newAccount();
+
+            $payload['externalAccountBinding'] = $this->buildEab(
+                json_encode(JsonWebKey::compute($accountKey), JSON_THROW_ON_ERROR),
+                $newAccountUrl,
+                $eab
+            );
+        }
 
         $response = $this->postToAccountUrl($payload);
 
@@ -49,6 +70,24 @@ public function get(): AccountData
         $this->throwError($response, 'Retrieving account failed');
     }
 
+    private function buildEab(string $jwkJson, string $url, EabCredentials $eab): array
+    {
+        $protected64 = Base64::urlSafeEncode(json_encode([
+            'alg' => 'HS256',
+            'kid' => $eab->kid,
+            'url' => $url,
+        ], JSON_THROW_ON_ERROR));
+
+        $payload64 = Base64::urlSafeEncode($jwkJson);
+        $hmacKey   = Base64::urlSafeDecode($eab->hmacKey);
+
+        return [
+            'protected' => $protected64,
+            'payload'   => $payload64,
+            'signature' => Base64::urlSafeEncode(hash_hmac('sha256', $protected64.'.'.$payload64, $hmacKey, true)),
+        ];
+    }
+
     private function signPayload(array $payload): array
     {
         return JsonWebSignature::generate(
@@ -69,7 +108,7 @@ private function postToAccountUrl(array $payload): Response
 
     protected function throwError(Response $response, string $defaultMessage): never
     {
-        $message = $response->getBody()['details'] ?? $defaultMessage;
+        $message = $response->getBody()['detail'] ?? $defaultMessage;
         $this->logResponse('error', $message, $response);
 
         throw new LetsEncryptClientException($message);
diff --git a/src/Endpoints/Directory.php b/src/Endpoints/Directory.php
@@ -48,4 +48,9 @@ public function revoke(): string
     {
         return $this->all()->getBody()['revokeCert'];
     }
+
+    public function renewalInfo(): ?string
+    {
+        return $this->all()->getBody()['renewalInfo'] ?? null;
+    }
 }
diff --git a/src/Endpoints/Order.php b/src/Endpoints/Order.php
@@ -78,6 +78,30 @@ public function get(string $id): OrderData
         };
     }
 
+    public function waitUntilValid(OrderData $order, int $maxAttempts = 10, int $sleepSeconds = 2): OrderData
+    {
+        for ($i = 0; $i < $maxAttempts; $i++) {
+            $response = $this->client->getHttpClient()->post(
+                $order->url,
+                $this->createKeyId($order->accountUrl, $order->url)
+            );
+
+            $body = $response->getBody();
+
+            if (($body['status'] ?? '') === 'valid') {
+                return OrderData::fromResponse($response, $order->accountUrl);
+            }
+
+            if (($body['status'] ?? '') === 'invalid') {
+                throw new LetsEncryptClientException('Order became invalid during finalization.');
+            }
+
+            sleep($sleepSeconds);
+        }
+
+        throw new LetsEncryptClientException("Order did not become valid after {$maxAttempts} attempts.");
+    }
+
     public function finalize(OrderData $orderData, string $csr): bool
     {
         if (!$orderData->isReady()) {
diff --git a/src/Endpoints/RenewalInfo.php b/src/Endpoints/RenewalInfo.php
@@ -0,0 +1,56 @@
+<?php
+
+namespace CoyoteCert\Endpoints;
+
+use DateTimeImmutable;
+use CoyoteCert\DTO\RenewalWindow;
+use CoyoteCert\Support\Base64;
+
+class RenewalInfo extends Endpoint
+{
+    public function get(string $certPem, string $issuerPem): ?RenewalWindow
+    {
+        $baseUrl = $this->client->directory()->renewalInfo();
+
+        if ($baseUrl === null) {
+            return null;
+        }
+
+        $url      = rtrim($baseUrl, '/') . '/' . $this->certId($certPem, $issuerPem);
+        $response = $this->client->getHttpClient()->get($url);
+
+        if ($response->getHttpResponseCode() !== 200) {
+            return null;
+        }
+
+        $body = $response->getBody();
+
+        return new RenewalWindow(
+            start:          new DateTimeImmutable($body['suggestedWindow']['start']),
+            end:            new DateTimeImmutable($body['suggestedWindow']['end']),
+            explanationUrl: $body['explanationURL'] ?? null,
+        );
+    }
+
+    private function certId(string $certPem, string $issuerPem): string
+    {
+        $issuerSpki = $this->spkiDer(openssl_get_publickey($issuerPem));
+        $issuerHash = Base64::urlSafeEncode(hash('sha256', $issuerSpki, true));
+
+        $parsed = openssl_x509_parse($certPem);
+        $serial = Base64::urlSafeEncode(hex2bin($parsed['serialNumberHex']));
+
+        return $issuerHash . '.' . $serial;
+    }
+
+    private function spkiDer(mixed $publicKey): string
+    {
+        // "BEGIN PUBLIC KEY" PEM wraps raw SPKI DER — strip the headers to get the DER bytes
+        $pem = openssl_pkey_get_details($publicKey)['key'];
+
+        return base64_decode(implode('', array_map(
+            'trim',
+            array_filter(explode("\n", $pem), static fn ($l) => !str_starts_with($l, '-----'))
+        )));
+    }
+}
diff --git a/src/Support/JsonWebKey.php b/src/Support/JsonWebKey.php
@@ -17,10 +17,25 @@ public static function compute(
 
         $details = openssl_pkey_get_details($privateKey);
 
+        if ($details['type'] === OPENSSL_KEYTYPE_EC) {
+            [$crv, $coordLen] = match ($details['ec']['curve_name']) {
+                'prime256v1' => ['P-256', 32],
+                'secp384r1'  => ['P-384', 48],
+                default      => throw new LetsEncryptClientException("Unsupported EC curve: {$details['ec']['curve_name']}"),
+            };
+
+            return [
+                'crv' => $crv,
+                'kty' => 'EC',
+                'x'   => Base64::urlSafeEncode(str_pad($details['ec']['x'], $coordLen, "\x00", STR_PAD_LEFT)),
+                'y'   => Base64::urlSafeEncode(str_pad($details['ec']['y'], $coordLen, "\x00", STR_PAD_LEFT)),
+            ];
+        }
+
         return [
-            'e' => Base64::urlSafeEncode($details['rsa']['e']),
+            'e'   => Base64::urlSafeEncode($details['rsa']['e']),
             'kty' => 'RSA',
-            'n' => Base64::urlSafeEncode($details['rsa']['n']),
+            'n'   => Base64::urlSafeEncode($details['rsa']['n']),
         ];
     }
 
diff --git a/src/Support/JsonWebSignature.php b/src/Support/JsonWebSignature.php
diff --git a/src/Support/KeyId.php b/src/Support/KeyId.php

Original file line number	Diff line number	Diff line change
`@@ -48,4 +48,9 @@ public function revoke(): string`
`48`	`48`	`{`
`49`	`49`	`return $this->all()->getBody()['revokeCert'];`
`50`	`50`	`}`
	`51`	`+`
	`52`	`+ public function renewalInfo(): ?string`
	`53`	`+ {`
	`54`	`+ return $this->all()->getBody()['renewalInfo'] ?? null;`
	`55`	`+ }`
`51`	`56`	`}`