Support JSignPdf 3.x CLI safely

[vitormattos]

JSignPdf has moved from the 2.x series to 3.x, but this PHP wrapper was created and tested with the older CLI behavior.

This wrapper should be checked and updated to support the latest stable JSignPdf 3.x release.

What needs to be done

• Run the wrapper with JSignPdf 2.3 and with the latest stable 3.x release using the same signing scenarios, then compare the generated commands and results.

• Check the CLI options currently used by the wrapper, especially signing, visible signature, page/coordinates, hash algorithm, TSA, output path and version detection. Update only what changed in JSignPdf 3.x.

• Verify the outputs that the wrapper parses today, such as --version, successful signing and signing errors. Add or update unit tests for these behaviors, especially where the current code depends on exact output strings.

  For example, the current signing code checks this exact message:

  Finished: Signature succesfully created.
  

  The version detection also depends on the format of the --version output. These assumptions should be checked against JSignPdf 3.x.

• Review how the command is built and ensure all dynamic values are safely escaped, including file paths, passwords and option values. Add unit tests with spaces and shell special characters.

• Add or update integration tests, when needed, to confirm the wrapper can really sign with JSignPdf 3.x.

• Document in the PR description the relevant CLI differences found between JSignPdf 2.3 and 3.x, including changes that required code or test updates.

Shell argument safety

The command builder must also be reviewed.

Values received by the wrapper must not be added directly to a shell command.

Paths, passwords, option values and other dynamic arguments must be safely escaped before they are passed to the shell.

Please review the complete command, not only the certificate password.

Special care is needed for values received through JSignParam::getJSignParameters(). If the current string-based API makes safe escaping difficult, it is OK to improve the internal command-building API, but try to keep the public API compatible when possible.

Tests should include values with spaces and shell special characters.

JSignPdf 3.x changes

Please also check the JSignPdf release notes and CLI help for relevant changes between 2.3 and the latest stable 3.x release.

The goal of this issue is compatibility with the current stable JSignPdf, not adding every new JSignPdf feature to the PHP API.

New features that could be useful to wrapper users can be documented in the PR description or proposed as follow-up issues.

Testing

Please add or update tests for at least:

• version detection;
• successful signing;
• signing errors;
• paths containing spaces;
• option values containing shell special characters;
• changed JSignPdf output, if applicable;
• new behavior required by JSignPdf 3.x.

The existing test suite should continue to pass.

Good first issue

This issue can be a good first contribution for someone interested in PHP and command-line integrations.

A good way to start is:

1. run the current test suite;
2. run the current state of this package with JSignPdf 2.3;
3. run the same commands with the latest stable JSignPdf 3.x;
4. compare the commands and outputs;
5. update one behavior at a time and add tests for it;
6. validate the test suite and make necessary fixes.

Please ask before doing a large API refactor. We prefer a small and focused compatibility change.

[YvesCesar]

I can work on this issue.