feat: add machine-readable validation reason codes

src/Model/ValidationReason.php

@@ -0,0 +1,16 @@
+<?php
+
+// SPDX-FileCopyrightText: 2026 LibreCode coop and contributors
+// SPDX-License-Identifier: AGPL-3.0-or-later
+
+declare(strict_types=1);
+
+namespace LibreSign\PdfSignatureValidator\Model;
+
+enum ValidationReason: string
+{
+    case DIGEST_MISMATCH = 'digest_mismatch';
+    case NO_BYTE_RANGE = 'no_byte_range';
+    case NO_BINARY_SIGNATURE = 'no_binary_signature';
+    case SIGNATURE_CERTIFICATE_MISMATCH = 'signature_certificate_mismatch';
+}

src/Model/ValidationResult.php

@@ -12,6 +12,7 @@ final class ValidationResult
     public function __construct(
         public readonly ValidationState $state,
         public readonly ?string $reason = null,
+        public readonly ?ValidationReason $reasonCode = null,
     ) {
         $this->isValid = $state->isValid();
     }

src/Parser/PdfSignatureValidator.php

@@ -9,6 +9,7 @@
 
 use LibreSign\PdfSignatureValidator\Exception\UnsignedPdfException;
 use LibreSign\PdfSignatureValidator\Model\ExtractedSignature;
+use LibreSign\PdfSignatureValidator\Model\ValidationReason;
 use LibreSign\PdfSignatureValidator\Model\ValidationResult;
 use LibreSign\PdfSignatureValidator\Model\ValidationState;
 
@@ -101,11 +102,13 @@ public function validateFromString(string $pdfContent, ?array $trustedRoots = nu
                     'signatureValidation' => new ValidationResult(
                         ValidationState::NOT_VERIFIED,
                         'No binary signature',
+                        ValidationReason::NO_BINARY_SIGNATURE,
                     ),
                     'certificates' => [],
                     'certificateValidation' => new ValidationResult(
                         ValidationState::CERT_NOT_VERIFIED,
                         'No binary signature',
+                        ValidationReason::NO_BINARY_SIGNATURE,
                     ),
                 ];
                 continue;

src/Parser/SignatureValidator.php

@@ -7,6 +7,7 @@
 
 namespace LibreSign\PdfSignatureValidator\Parser;
 
+use LibreSign\PdfSignatureValidator\Model\ValidationReason;
 use LibreSign\PdfSignatureValidator\Model\ValidationResult;
 use LibreSign\PdfSignatureValidator\Model\ValidationState;
 
@@ -33,6 +34,7 @@ public function verifyDigest(
             return new ValidationResult(
                 ValidationState::NOT_VERIFIED,
                 'No ByteRange in signature',
+                ValidationReason::NO_BYTE_RANGE,
             );
         }
 
@@ -47,6 +49,7 @@ public function verifyDigest(
         return new ValidationResult(
             ValidationState::DIGEST_MISMATCH,
             'PDF content hash does not match signed digest',
+            ValidationReason::DIGEST_MISMATCH,
         );
     }
 
@@ -66,6 +69,7 @@ public function verifySignature(
         return new ValidationResult(
             ValidationState::SIGNATURE_INVALID,
             'Signature does not match certificate',
+            ValidationReason::SIGNATURE_CERTIFICATE_MISMATCH,
         );
     }
 

tests/Unit/Parser/SignatureValidatorTest.php

@@ -7,6 +7,7 @@
 
 namespace LibreSign\PdfSignatureValidator\Tests\Unit\Parser;
 
+use LibreSign\PdfSignatureValidator\Model\ValidationReason;
 use LibreSign\PdfSignatureValidator\Parser\CertificateExtractor;
 use LibreSign\PdfSignatureValidator\Parser\SignatureValidator;
 use PHPUnit\Framework\TestCase;
@@ -67,6 +68,7 @@ public function testVerifyDigestWithMismatchedContent(): void
 
         $this->assertFalse($result->isValid);
         $this->assertSame('Digest Mismatch.', $result->state->value);
+        $this->assertSame(ValidationReason::DIGEST_MISMATCH, $result->reasonCode);
     }
 
     public function testVerifyDigestWithoutByteRange(): void
@@ -79,6 +81,7 @@ public function testVerifyDigestWithoutByteRange(): void
         );
 
         $this->assertFalse($result->isValid);
+        $this->assertSame(ValidationReason::NO_BYTE_RANGE, $result->reasonCode);
     }
 
     public function testVerifySignatureWithValidOpenSslSignature(): void
@@ -128,5 +131,6 @@ public function testVerifySignatureWithInvalidSignatureBytes(): void
         );
 
         $this->assertFalse($result->isValid);
+        $this->assertSame(ValidationReason::SIGNATURE_CERTIFICATE_MISMATCH, $result->reasonCode);
     }
 }