From da8499b88be5e2571d483a493e050b258890c943 Mon Sep 17 00:00:00 2001
From: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>
Date: Fri, 24 Apr 2026 11:33:32 -0300
Subject: [PATCH] feat: add machine-readable validation reason codes

Signed-off-by: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>
---
 src/Model/ValidationReason.php               | 16 ++++++++++++++++
 src/Model/ValidationResult.php               |  1 +
 src/Parser/PdfSignatureValidator.php         |  3 +++
 src/Parser/SignatureValidator.php            |  4 ++++
 tests/Unit/Parser/SignatureValidatorTest.php |  4 ++++
 5 files changed, 28 insertions(+)
 create mode 100644 src/Model/ValidationReason.php

diff --git a/src/Model/ValidationReason.php b/src/Model/ValidationReason.php
new file mode 100644
index 0000000..209bc2b
--- /dev/null
+++ b/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';
+}
diff --git a/src/Model/ValidationResult.php b/src/Model/ValidationResult.php
index 87330b8..fb22dc9 100644
--- a/src/Model/ValidationResult.php
+++ b/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();
     }
diff --git a/src/Parser/PdfSignatureValidator.php b/src/Parser/PdfSignatureValidator.php
index 7a9a245..6d42882 100644
--- a/src/Parser/PdfSignatureValidator.php
+++ b/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;
diff --git a/src/Parser/SignatureValidator.php b/src/Parser/SignatureValidator.php
index 23ccdd6..97a613b 100644
--- a/src/Parser/SignatureValidator.php
+++ b/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,
         );
     }
 
diff --git a/tests/Unit/Parser/SignatureValidatorTest.php b/tests/Unit/Parser/SignatureValidatorTest.php
index f644384..ca6709b 100644
--- a/tests/Unit/Parser/SignatureValidatorTest.php
+++ b/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);
     }
 }