From 37f3b65cdb73fbbb2523e4b26168390b2cd0b909 Mon Sep 17 00:00:00 2001
From: Vitor Mattos <vitor@php.rio>
Date: Fri, 20 Mar 2026 16:06:50 -0300
Subject: [PATCH 1/6] chore(git): ignore local env and secret directories

Signed-off-by: Vitor Mattos <vitor@php.rio>
---
 .gitignore | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/.gitignore b/.gitignore
index 6e94e98..c81ed4b 100644
--- a/.gitignore
+++ b/.gitignore
@@ -3,3 +3,6 @@
 /.php-cs-fixer.cache
 /.phpunit.cache
 /composer.lock
+/.env
+/.env.local
+/.secrets/

From b2c309ba473436f69ff357bebcb2a4e53b369616 Mon Sep 17 00:00:00 2001
From: Vitor Mattos <vitor@php.rio>
Date: Fri, 20 Mar 2026 16:06:50 -0300
Subject: [PATCH 2/6] chore(env): add sandbox integration env template

Signed-off-by: Vitor Mattos <vitor@php.rio>
---
 .env.example | 20 ++++++++++++++++++++
 1 file changed, 20 insertions(+)
 create mode 100644 .env.example

diff --git a/.env.example b/.env.example
new file mode 100644
index 0000000..f6cde8a
--- /dev/null
+++ b/.env.example
@@ -0,0 +1,20 @@
+# Local sandbox setup for nfse-php smoke tests
+# Copy to .env.local and fill the secret values.
+
+# Full HEAD URL for sandbox mTLS smoke test
+# Example:
+# NFSE_HEAD_URL="https://adn.producaorestrita.nfse.gov.br/dps/00000000000000000000000000000000000000000000"
+NFSE_HEAD_URL="https://adn.producaorestrita.nfse.gov.br/dps/CHANGE_ME"
+
+# PFX certificate used for mTLS (local file, never commit)
+NFSE_MTLS_PFX_PATH=".secrets/pfx/2025-LibreCode.pfx"
+NFSE_MTLS_PFX_PASSWORD="CHANGE_ME"
+
+# Optional: set to 1 to print TLS handshake details
+NFSE_CURL_VERBOSE=0
+
+# Optional OpenBao/Vault settings (if needed by local app wiring)
+VAULT_ADDR="http://openbao:8200"
+VAULT_TOKEN=""
+VAULT_ROLE_ID=""
+VAULT_SECRET_ID=""

From b8d8435c7e2e9a801cbc899d19572e16f9903a90 Mon Sep 17 00:00:00 2001
From: Vitor Mattos <vitor@php.rio>
Date: Fri, 20 Mar 2026 16:06:50 -0300
Subject: [PATCH 3/6] test(support): load local env for optional integration
 suite

Signed-off-by: Vitor Mattos <vitor@php.rio>
---
 tests/Support/LoadsLocalEnv.php | 62 +++++++++++++++++++++++++++++++++
 1 file changed, 62 insertions(+)
 create mode 100644 tests/Support/LoadsLocalEnv.php

diff --git a/tests/Support/LoadsLocalEnv.php b/tests/Support/LoadsLocalEnv.php
new file mode 100644
index 0000000..7220ce6
--- /dev/null
+++ b/tests/Support/LoadsLocalEnv.php
@@ -0,0 +1,62 @@
+<?php
+
+// SPDX-FileCopyrightText: 2026 LibreCode coop and contributors
+// SPDX-License-Identifier: AGPL-3.0-or-later
+
+declare(strict_types=1);
+
+namespace LibreCodeCoop\NfsePHP\Tests\Support;
+
+trait LoadsLocalEnv
+{
+    private static bool $envLoaded = false;
+
+    protected static function loadLocalEnv(): void
+    {
+        if (self::$envLoaded) {
+            return;
+        }
+
+        self::$envLoaded = true;
+
+        $root = dirname(__DIR__, 2);
+
+        self::loadFile($root . '/.env.local');
+        self::loadFile($root . '/.env');
+    }
+
+    private static function loadFile(string $path): void
+    {
+        if (!is_file($path)) {
+            return;
+        }
+
+        $lines = file($path, FILE_IGNORE_NEW_LINES | FILE_SKIP_EMPTY_LINES);
+
+        if ($lines === false) {
+            return;
+        }
+
+        foreach ($lines as $line) {
+            $line = trim($line);
+
+            if ($line === '' || str_starts_with($line, '#') || !str_contains($line, '=')) {
+                continue;
+            }
+
+            [$key, $value] = explode('=', $line, 2);
+
+            $key = trim($key);
+            if ($key === '' || getenv($key) !== false) {
+                continue;
+            }
+
+            $value = trim($value);
+            $value = trim($value, "\"'");
+
+            putenv($key . '=' . $value);
+            $_ENV[$key] = $value;
+            $_SERVER[$key] = $value;
+        }
+    }
+}

From 94eaa77c1c7412c896c23ea6e926478d57dffacf Mon Sep 17 00:00:00 2001
From: Vitor Mattos <vitor@php.rio>
Date: Fri, 20 Mar 2026 16:06:50 -0300
Subject: [PATCH 4/6] test(integration): add sandbox mTLS head connectivity
 check

Signed-off-by: Vitor Mattos <vitor@php.rio>
---
 .../Integration/Http/SandboxMtlsHeadTest.php  | 67 +++++++++++++++++++
 1 file changed, 67 insertions(+)
 create mode 100644 tests/Integration/Http/SandboxMtlsHeadTest.php

diff --git a/tests/Integration/Http/SandboxMtlsHeadTest.php b/tests/Integration/Http/SandboxMtlsHeadTest.php
new file mode 100644
index 0000000..33052c4
--- /dev/null
+++ b/tests/Integration/Http/SandboxMtlsHeadTest.php
@@ -0,0 +1,67 @@
+<?php
+
+// SPDX-FileCopyrightText: 2026 LibreCode coop and contributors
+// SPDX-License-Identifier: AGPL-3.0-or-later
+
+declare(strict_types=1);
+
+namespace LibreCodeCoop\NfsePHP\Tests\Integration\Http;
+
+use LibreCodeCoop\NfsePHP\Tests\Support\LoadsLocalEnv;
+use LibreCodeCoop\NfsePHP\Tests\TestCase;
+
+/**
+ * Optional sandbox connectivity smoke test (mTLS).
+ * Skips if env vars are not configured.
+ */
+class SandboxMtlsHeadTest extends TestCase
+{
+    use LoadsLocalEnv;
+
+    public function testSandboxHeadWithMtlsWhenEnvIsPresent(): void
+    {
+        self::loadLocalEnv();
+
+        $url = getenv('NFSE_HEAD_URL') ?: '';
+        $pfxPath = getenv('NFSE_MTLS_PFX_PATH') ?: '';
+        $pfxPassword = getenv('NFSE_MTLS_PFX_PASSWORD') ?: '';
+
+        if ($url === '' || $pfxPath === '' || $pfxPassword === '') {
+            self::markTestSkipped('Set NFSE_HEAD_URL, NFSE_MTLS_PFX_PATH and NFSE_MTLS_PFX_PASSWORD to run sandbox mTLS test.');
+        }
+
+        if (!str_starts_with($pfxPath, '/')) {
+            $pfxPath = dirname(__DIR__, 3) . '/' . ltrim($pfxPath, '/');
+        }
+
+        if (!is_file($pfxPath)) {
+            self::markTestSkipped('Configured PFX file does not exist for mTLS test.');
+        }
+
+        $cmd = sprintf(
+            'curl --silent --show-error --output /dev/null --write-out "%%{http_code}" --head --cert-type P12 --cert %s %s; echo "|exit:$?"',
+            escapeshellarg($pfxPath . ':' . $pfxPassword),
+            escapeshellarg($url)
+        );
+
+        $result = shell_exec($cmd);
+
+        self::assertNotFalse($result, 'curl execution failed');
+
+        $result = trim((string) $result);
+
+        if (!str_contains($result, '|exit:')) {
+            self::fail('Unexpected curl result format.');
+        }
+
+        [$httpCode, $exitPart] = explode('|exit:', $result, 2);
+        $httpCode = trim($httpCode);
+        $exitCode = (int) trim($exitPart);
+
+        if ($exitCode !== 0) {
+            self::markTestSkipped('mTLS curl failed in local runtime (likely OpenSSL/PFX compatibility).');
+        }
+
+        self::assertContains($httpCode, ['200', '401', '403', '404']);
+    }
+}

From e95a09b5f614aed4fc74c099f7d678af70f35e4d Mon Sep 17 00:00:00 2001
From: Vitor Mattos <vitor@php.rio>
Date: Fri, 20 Mar 2026 16:06:50 -0300
Subject: [PATCH 5/6] test(integration): add real pfx signer integration
 coverage

Signed-off-by: Vitor Mattos <vitor@php.rio>
---
 .../Xml/DpsSignerIntegrationTest.php          | 70 +++++++++++++++++++
 1 file changed, 70 insertions(+)
 create mode 100644 tests/Integration/Xml/DpsSignerIntegrationTest.php

diff --git a/tests/Integration/Xml/DpsSignerIntegrationTest.php b/tests/Integration/Xml/DpsSignerIntegrationTest.php
new file mode 100644
index 0000000..5fb3f33
--- /dev/null
+++ b/tests/Integration/Xml/DpsSignerIntegrationTest.php
@@ -0,0 +1,70 @@
+<?php
+
+// SPDX-FileCopyrightText: 2026 LibreCode coop and contributors
+// SPDX-License-Identifier: AGPL-3.0-or-later
+
+declare(strict_types=1);
+
+namespace LibreCodeCoop\NfsePHP\Tests\Integration\Xml;
+
+use LibreCodeCoop\NfsePHP\Exception\PfxImportException;
+use LibreCodeCoop\NfsePHP\SecretStore\NoOpSecretStore;
+use LibreCodeCoop\NfsePHP\Tests\Support\LoadsLocalEnv;
+use LibreCodeCoop\NfsePHP\Tests\TestCase;
+use LibreCodeCoop\NfsePHP\Xml\DpsSigner;
+
+/**
+ * Optional integration test:
+ * - Uses real PFX when env vars are available
+ * - Skips cleanly when env vars are absent
+ */
+class DpsSignerIntegrationTest extends TestCase
+{
+    use LoadsLocalEnv;
+
+    public function testSignsXmlWithConfiguredPfxWhenEnvIsPresent(): void
+    {
+        self::loadLocalEnv();
+
+        $cnpj = getenv('NFS_TEST_CNPJ') ?: '11222333000181';
+        $pfxPath = getenv('NFSE_MTLS_PFX_PATH') ?: '';
+        $pfxPassword = getenv('NFSE_MTLS_PFX_PASSWORD') ?: '';
+
+        if ($pfxPath === '' || $pfxPassword === '') {
+            self::markTestSkipped('Set NFSE_MTLS_PFX_PATH and NFSE_MTLS_PFX_PASSWORD to run real-PFX integration test.');
+        }
+
+        if (!str_starts_with($pfxPath, '/')) {
+            $pfxPath = dirname(__DIR__, 3) . '/' . ltrim($pfxPath, '/');
+        }
+
+        if (!is_file($pfxPath)) {
+            self::markTestSkipped('Configured PFX file does not exist for integration test.');
+        }
+
+        $store = new NoOpSecretStore();
+        $store->put('pfx/' . $cnpj, [
+            'pfx_path' => $pfxPath,
+            'password' => $pfxPassword,
+        ]);
+
+        $signer = new DpsSigner($store);
+        $xml = '<DPS><infDPS Id="DPS123"><x>abc</x></infDPS></DPS>';
+
+        try {
+            $signed = $signer->sign($xml, $cnpj);
+        } catch (PfxImportException $e) {
+            $message = strtolower($e->getMessage());
+
+            // Local OpenSSL runtime may not support legacy PKCS#12 algorithms.
+            if (str_contains($message, 'digital envelope routines') || str_contains($message, 'asn1 encoding routines')) {
+                self::markTestSkipped('Local OpenSSL runtime cannot import this PFX format.');
+            }
+
+            throw $e;
+        }
+
+        self::assertStringContainsString('<Signature', $signed);
+        self::assertStringContainsString('DigestValue', $signed);
+    }
+}

From 0bcc3786e39e0f816dd72e8fce87b1e7dad187be Mon Sep 17 00:00:00 2001
From: Vitor Mattos <vitor@php.rio>
Date: Fri, 20 Mar 2026 16:12:54 -0300
Subject: [PATCH 6/6] chore(reuse): add SPDX header to env example

Signed-off-by: Vitor Mattos <vitor@php.rio>
---
 .env.example | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/.env.example b/.env.example
index f6cde8a..ae567b1 100644
--- a/.env.example
+++ b/.env.example
@@ -1,3 +1,6 @@
+# SPDX-FileCopyrightText: 2026 LibreCode coop and contributors
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
 # Local sandbox setup for nfse-php smoke tests
 # Copy to .env.local and fill the secret values.