Update JSignPdf to 3.x #8068

LibreSign currently uses JSignPdf 2.3.0:

https://github.com/LibreSign/libresign/blob/main/lib/Service/Install/InstallService.php#L53

JSignPdf already has stable 3.x releases with important changes to its CLI, packaging and signing behavior.

Before updating LibreSign, the PHP wrapper must support JSignPdf 3.x:

JSignPdf/jsignpdf-php#52

This issue should be worked on after that issue is completed and a new version of jsignpdf-php is available.

What needs to be done

• Update LibreSign to the new jsignpdf-php version with JSignPdf 3.x support.
• Update the JSignPdf version, download source, checksum and installation logic in InstallService.
• Check the JSignPdf 3.x package structure and choose the correct package for LibreSign. JSignPdf 3.1 removed the old fat JAR and provides a minimal package for headless/CLI use, so changing only the version and checksum may not be enough.
• Review JSignPdfHandler and confirm that the current JSignPdf options still work correctly, including visible signatures, page and coordinates, hash algorithm, TSA, certification and output behavior.
• Update the unit tests for all behavior changed by this migration.
• Run the signing tests with JSignPdf 3.x and confirm that the existing LibreSign signing flows still work.

JSignPdf options and arguments

Safe command building and shell escaping are mainly handled by the PHP wrapper and are part of:

JSignPdf/jsignpdf-php#52

However, LibreSign also prepares options and values before sending them to the wrapper.

Review this integration and, when the new wrapper supports it, prefer passing structured values instead of preparing shell syntax inside LibreSign.

Check the dynamic values already used by LibreSign, such as:

• signature text;
• file paths;
• TSA URL;
• TSA policy OID;
• TSA username and password;
• page and coordinates;
• hash algorithm;
• certification level.

When several values follow the same logic, prefer PHPUnit data providers instead of many similar tests.

The data providers should include normal values and useful edge cases, such as spaces, quotes, shell special characters, empty values, numeric values, URLs and file paths.

The tests should confirm that LibreSign sends the expected values to the wrapper without creating unsafe or invalid command arguments.

Testing requirements

The migration must include unit tests for the affected classes.

At minimum, review:

• JSignPdfHandlerTest;
• the tests for InstallService, if the installation logic changes.

If other classes are changed, update their tests too.

For JSignPdfHandlerTest, use data providers when this helps test different options and values without repeating the same test logic.

The tests should cover the relevant current behavior and any behavior changed by JSignPdf 3.x, including when applicable:

• visible and invisible signatures;
• page and coordinates;
• hash algorithms;
• TSA parameters;
• certification level;
• signature text;
• file paths;
• optional values;
• values with spaces and shell special characters.

Do not only change expected values to make old tests pass. Add or change tests when the JSignPdf 3.x behavior is different.

Mutation testing

Run mutation testing for the classes directly affected by this migration.

The affected scope must reach 100% mutation score, with no escaped mutants and no mutation test errors.

The tests should detect changes in the relevant JSignPdf integration logic, not only execute the code.

Keep the mutation test scope focused on the classes changed by this issue. There is no need to run mutation tests for unrelated parts of LibreSign.

If a mutant cannot be killed for a valid technical reason, explain the reason in the PR.

Quality gates

Before the PR is ready for review, run the project checks using the scripts available in composer.json.

The affected PHPUnit tests and mutation tests must pass, and the PR must also pass:

• Psalm;
• PHPCS.

Do not ignore new warnings, errors or failed checks.

Check new JSignPdf features

JSignPdf 3.x also added, or is adding, features that may be useful to LibreSign.

Review the JSignPdf release notes and CLI changes and add a short section to the PR description with useful features found during this work.

Do not implement these features in this PR.

Some examples to check are:

• new signing engines and DSS / PAdES support;
• changes to append and overwrite behavior;
• safer ways to provide passwords;
• new CLI options;
• support for existing PDF signature fields.

The support being developed in JSignPdf 3.2 for signing an existing PDF signature field is especially interesting for LibreSign.

In the future, this could allow LibreSign to receive a PDF with signature fields already defined and associate each field with a signer instead of creating the signature position.

If a new JSignPdf feature looks useful for LibreSign, create a separate follow-up issue for it.

Expected result

After this change:

• LibreSign uses the latest supported stable JSignPdf 3.x release;
• LibreSign uses the updated jsignpdf-php wrapper;
• installation works with the new JSignPdf package structure;
• existing signing flows continue to work;
• options and values are correctly passed to the wrapper;
• affected behavior is covered by unit and mutation tests;
• Psalm and PHPCS pass;
• useful new JSignPdf features are listed for future work.

Keep this PR focused on the JSignPdf 3.x migration. New signing features should be handled in separate issues.