[stable32] fix: improve TSA DNS/network error guidance (#7431)

* test: require DNS/network/firewall hint for unresolved TSA host

Signed-off-by: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>

* fix: clarify TSA DNS/network/firewall validation failure

Signed-off-by: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>

* test: cover TSA handler DNS/network/firewall guidance

Signed-off-by: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>

* fix: align TSA handler errors with connectivity guidance

Signed-off-by: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>

---------

Signed-off-by: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>
Co-authored-by: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>

Author: backportbot-libresign[bot]

lib/Handler/SignEngine/JSignPdfHandler.php

@@ -671,10 +671,10 @@ private function checkTsaError(string $errorMessage): void {
 
 		if ($isTsaError) {
 			if (str_contains($errorMessage, 'Invalid TSA') && preg_match("/Invalid TSA '([^']+)'/", $errorMessage, $matches)) {
-				$friendlyMessage = 'Timestamp Authority (TSA) service is unavailable or misconfigured: ' . $matches[1];
+				$friendlyMessage = 'Timestamp Authority (TSA) service is unavailable. Check DNS/network/firewall connectivity from this server: ' . $matches[1];
 			} else {
 				$friendlyMessage = 'Timestamp Authority (TSA) service error.' . "\n"
-					. 'Please check the TSA configuration.';
+					. 'Check TSA endpoint and DNS/network/firewall connectivity from this server.';
 			}
 			throw new LibresignException($friendlyMessage);
 		}

lib/Service/TsaValidationService.php

@@ -62,7 +62,7 @@ private function validateTsaHostResolution(string $tsaUrl): void {
 		}
 
 		if (!@gethostbyname($host) || gethostbyname($host) === $host) {
-			throw new LibresignException('Timestamp Authority (TSA) service is unavailable or misconfigured: ' . $tsaUrl);
+			throw new LibresignException('Timestamp Authority (TSA) service is unavailable. Check DNS/network/firewall connectivity from this server: ' . $tsaUrl);
 		}
 	}
 }

tests/php/Unit/Handler/SignEngine/JSignPdfHandlerTest.php

@@ -12,6 +12,7 @@
 use OCA\Libresign\DataObjects\VisibleElementAssoc;
 use OCA\Libresign\Db\FileElement;
 use OCA\Libresign\Enum\DocMdpLevel;
+use OCA\Libresign\Exception\LibresignException;
 use OCA\Libresign\Handler\CertificateEngine\CertificateEngineFactory;
 use OCA\Libresign\Handler\SignEngine\JSignPdfHandler;
 use OCA\Libresign\Helper\JavaHelper;
@@ -732,4 +733,26 @@ public static function providerGetSignatureText(): array {
 			['GRAPHIC_ONLY',     'a$a',  '""'],
 		];
 	}
+
+	public function testCheckTsaErrorInvalidTsaMentionsDnsNetworkFirewall(): void {
+		$jSignPdfHandler = $this->getInstance();
+
+		$this->expectException(LibresignException::class);
+		$this->expectExceptionMessage('Timestamp Authority (TSA) service is unavailable. Check DNS/network/firewall connectivity from this server: https://invalid-tsa.example.com/tsr');
+
+		self::invokePrivate($jSignPdfHandler, 'checkTsaError', [
+			"Invalid TSA 'https://invalid-tsa.example.com/tsr'",
+		]);
+	}
+
+	public function testCheckTsaErrorUnknownHostMentionsDnsNetworkFirewall(): void {
+		$jSignPdfHandler = $this->getInstance();
+
+		$this->expectException(LibresignException::class);
+		$this->expectExceptionMessage("Timestamp Authority (TSA) service error.\nCheck TSA endpoint and DNS/network/firewall connectivity from this server.");
+
+		self::invokePrivate($jSignPdfHandler, 'checkTsaError', [
+			'TSAClientBouncyCastle: java.net.UnknownHostException: invalid-tsa.example.com',
+		]);
+	}
 }

tests/php/Unit/Service/TsaValidationServiceTest.php

@@ -79,7 +79,7 @@ public static function provideInvalidTsaUrls(): array {
 			],
 			'unresolvable host' => [
 				'https://invalid-tsa-server-abc123xyz.example.com/tsr',
-				'/Timestamp Authority \(TSA\) service is unavailable or misconfigured/',
+				'/Timestamp Authority \(TSA\) service is unavailable\. Check DNS\/network\/firewall connectivity from this server/',
 				true,
 			],
 		];