Skip to content

Generalize SignEngineFactory to return the sign engine interface #8344

Closed

Description

@vitormattos

This is part of #8335.

LibreSign already has the ISignEngineHandler interface, and the current sign engine handlers implement it through SignEngineHandler.

However, SignEngineFactory::resolve() currently declares its return type using the concrete handlers:

public function resolve(string $extension): Pkcs12Handler|Pkcs7Handler

This means every new handler added to this factory would also require changing its public return type.

Before adding new signing paths, we should make the factory depend on the existing handler abstraction instead.

Current behavior

The current factory selects between two existing signing implementations:

  • PDF files use Pkcs12Handler, which handles the current PDF signing flow.
  • Other file types use Pkcs7Handler, which creates a detached PKCS#7 (.p7s) signature.

The extension matching is case-insensitive.

flowchart LR
    E["File extension"] --> F["SignEngineFactory"]

    F -->|"pdf"| PDF["Pkcs12Handler<br/>PDF signing"]
    F -->|"other extension"| P7["Pkcs7Handler<br/>Detached PKCS#7 signature"]

    PDF --> I["ISignEngineHandler"]
    P7 --> I
Loading

Goal

Change SignEngineFactory so its public contract returns ISignEngineHandler while preserving exactly the same runtime behavior.

The factory must continue selecting:

  • Pkcs12Handler for PDF files;
  • Pkcs7Handler for non-PDF files.

This issue must not add external signing yet.

Expected change

Update:

lib/Handler/SignEngine/SignEngineFactory.php

from:

public function resolve(string $extension): Pkcs12Handler|Pkcs7Handler

to:

public function resolve(string $extension): ISignEngineHandler

Do not change how the handler is selected.

The returned handler must still be the exact instance provided by the dependency injection container.

Tests

Add focused unit tests for SignEngineFactory.

Mock Psr\Container\ContainerInterface and provide mocked handler instances.

Use a PHPUnit DataProvider to cover at least:

Extension Expected handler
pdf Pkcs12Handler
PDF Pkcs12Handler
Pdf Pkcs12Handler
docx Pkcs7Handler
odt Pkcs7Handler
txt Pkcs7Handler

For each case, verify that:

  • the expected handler class is requested from the container;
  • resolve() returns the same handler instance supplied by the container;
  • the returned value implements ISignEngineHandler.

Follow the existing LibreSign PHPUnit conventions for namespace, test location, mocks and naming.

Why this helps #8335

External signing will introduce signing behavior that does not fit the current certificate-and-password flow.

This issue does not decide how that future handler will work.

It only removes an unnecessary concrete return-type restriction from the current factory, allowing the existing abstraction to remain stable when new signing paths are introduced later.

The current PDF and detached PKCS#7 signing paths must remain unchanged.

The external signing prepare/finalize architecture is being discussed separately in:

SignerPHP/signer-php#25

Scope boundaries

Please keep this change focused.

Do not:

  • add a new signing handler;
  • change ISignEngineHandler;
  • change SignEngineHandler;
  • change Pkcs12Handler;
  • change Pkcs7Handler;
  • change the extension-to-handler mapping;
  • change the detached PKCS#7 implementation;
  • add CSC or ICP-Brasil PSC support;
  • add external signing methods;
  • change any signing workflow.

Good first issue

This is a small backend refactor based on an abstraction that already exists in LibreSign.

The main work is:

  • change the return type of SignEngineFactory::resolve() to ISignEngineHandler;
  • keep the existing PDF and detached PKCS#7 handler selection unchanged;
  • add focused unit tests using a DataProvider;
  • verify that the dependency injection container is asked for the expected handler;
  • verify that the same handler instance is returned.

No new signing architecture, provider integration, frontend change, database migration or API change is needed.

Please keep the change focused. If the implementation seems to require changes to ISignEngineHandler, new handlers or a broader signing-engine refactor, discuss it in this issue before adding that complexity.

Additional context

  • If you have questions, feel free to ask in this issue.
  • Give a ⭐️ star to this repository if you find LibreSign useful and would like to support the project.
  • You can also join our community: https://t.me/LibreSign

Done when

  • SignEngineFactory::resolve() returns ISignEngineHandler.
  • PDF files still resolve to Pkcs12Handler.
  • PDF extension matching remains case-insensitive.
  • Non-PDF files still resolve to the existing detached PKCS#7 signing path through Pkcs7Handler.
  • Unit tests cover the factory behavior using a DataProvider.
  • The expected handler class is requested from the container.
  • The same handler instance provided by the container is returned.
  • The returned handler satisfies ISignEngineHandler.
  • No production signing behavior is changed.

Activity

  1. added theissue type on Sep 11, 2026
  2. maia-andre commented on Sep 11, 2026

    @maia-andre
    Contributor

    I would like to work on this one:

    • lib/Handler/SignEngine/SignEngineFactory.php
    • tests/php/Unit/Handler/SignEngine/SignEngineFactoryTest.php

    I went through the change before claiming it, and there are two things worth reporting first, because one of them decides how many files the pull request touches.

    The test file already exists

    tests/php/Unit/Handler/SignEngine/SignEngineFactoryTest.php is already there and already uses a DataProvider, covering pdf, PDF, odt, ODT, jpg, JPG, png, PNG, txt and TXT with assertInstanceOf.

    So the case-insensitivity and the extension-to-handler mapping from your table are covered. What it does not cover is the rest of your checklist, because it resolves the real container with \OCP\Server::get(ContainerInterface::class) instead of mocking it:

    • it cannot assert that the expected handler class is the one requested from the container;
    • it cannot assert that the returned value is the same instance the container supplied;
    • it does not assert ISignEngineHandler.

    My plan is to convert this test to a mocked ContainerInterface, keep the extensions it already covers, add Pdf from your table, and add the three assertions above. That covers every item under "Tests" without creating a second test file.

    The one-line change does not pass psalm on its own

    I applied only the return-type change and ran psalm in the devcontainer (vendor-bin/psalm, errorLevel="5", the project config). It produces two new errors, both in SignFileService:

    ERROR: MoreSpecificReturnType - lib/Service/SignFileService.php:951:49
      The declared return type 'SignEngineHandler' for SignFileService::identifyEngine
      is more specific than the inferred return type 'ISignEngineHandler'
    
    ERROR: LessSpecificReturnStatement - lib/Service/SignFileService.php:952:10
      The type 'ISignEngineHandler' is more general than the declared return type
      'SignEngineHandler' for SignFileService::identifyEngine
    

    SignFileService::identifyEngine() is the only place that consumes the factory with a declared type — PdfSignatureDetectionService::hasSignatures(), the other caller, assigns to a local variable and only calls getCertificateChain(), which is on the interface, so it is unaffected.

    Widening three declarations in SignFileService clears both errors:

    • private ?SignEngineHandler $engine (line 87)
    • identifyEngine(): SignEngineHandler (line 951)
    • getEngine(): SignEngineHandler (line 1226)

    With those three changed to ISignEngineHandler, psalm reports no new errors. I verified this by running psalm over SignEngineFactory, SignFileService, PfxProvider and PdfSignatureDetectionService before and after, and the only difference against the unmodified branch is one informational issue, described next.

    What that informational issue tells us

    INFO: ArgumentTypeCoercion - lib/Service/SignFileService.php:1240:52
      Argument 1 of SignFileService::getOrGeneratePfxContent expects SignEngineHandler,
      but parent type ISignEngineHandler provided
    

    It is informational at errorLevel="5", so it does not fail CI, and it is honest rather than accidental: PfxProvider::getOrGeneratePfx() declares SignEngineHandler and calls three methods that are not part of ISignEngineHandler:

    • setLeafExpiryOverrideInDays()
    • generateCertificate()
    • getPfxOfCurrentSigner()

    In other words, the signing path resolved by the factory is expressible through the interface, but the certificate-provisioning path around it is not. That looks like information #8335 will want later, so I would rather leave it visible than paper over it.

    What I plan to do

    Following your scope boundaries exactly:

    1. SignEngineFactory::resolve() returns ISignEngineHandler; the match and the container lookups stay byte-for-byte the same.
    2. The three declarations in SignFileService listed above widen to ISignEngineHandler, so psalm stays green. Nothing else in that file changes.
    3. SignEngineFactoryTest moves to a mocked container and gains the instance-identity, container-request and ISignEngineHandler assertions.

    I will not touch ISignEngineHandler, SignEngineHandler, Pkcs12Handler, Pkcs7Handler, the extension mapping, the detached PKCS#7 implementation or any signing workflow, and I will not add a handler or any external signing code.

    PfxProvider stays as it is. Making it accept the interface would require adding those three certificate methods to ISignEngineHandler, which your scope boundaries rule out, and which I think belongs to the external-signing design rather than to this refactor.

    One question before I open the pull request

    Item 2 is the only part that goes beyond the file named in the issue. SignFileService is not in your "do not change" list, and without it the psalm job fails, so I read it as inside the intended scope — but it is your call. Is widening those three declarations acceptable here, or would you rather this pull request stay strictly inside SignEngineFactory and have the type consequences handled separately?

    I will start on the branch with that plan unless you say otherwise; if you prefer a different split, tell me and I will adjust before opening anything.

  3. maia-andre commented on Sep 11, 2026

    @maia-andre
    Contributor

    Opened #8347 with the plan above.

    It follows the minimal variant: the factory return type, the three declarations in SignFileService that carry the resolved engine, and the factory test converted to a mocked container. Nothing on your "do not change" list was touched, and PfxProvider was left alone.

    Local results, in the devcontainer:

    check result
    psalm on the four files involved same 5 pre-existing MissingDependency errors as the unmodified branch, no new error
    SignEngineFactoryTest OK, 12 tests, 48 assertions
    SignFileServiceTest + PfxProviderTest + PdfSignatureDetectionServiceTest OK, 165 tests, 386 assertions
    php-cs-fixer on the three changed files nothing to fix

    The pull request is open rather than waiting because the question I left above is about the split, not about whether the change is possible — the diff is small enough to answer it directly. If you would rather keep it strictly inside SignEngineFactory, tell me and I will rework it; the psalm job fails in that shape, so it would need a different solution for the two errors.

  4. moved this from 0. Backlog to 4. to release in LibreSign Roadmapon Sep 11, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    backendBackend workgood first issueGood for newcomersphpWork involving PHP code

    Type

    Fields

    Priority

    High

    Projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions