Repository navigation
Description
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|Pkcs7HandlerThis 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
Goal
Change SignEngineFactory so its public contract returns ISignEngineHandler while preserving exactly the same runtime behavior.
The factory must continue selecting:
Pkcs12Handlerfor PDF files;Pkcs7Handlerfor 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|Pkcs7Handlerto:
public function resolve(string $extension): ISignEngineHandlerDo 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:
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()toISignEngineHandler; - 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()returnsISignEngineHandler. - 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.
Metadata
Metadata
Assignees
Labels
Type
Fields
Priority
Projects
- StatusShow more project fieldsNo status
Activity
maia-andre commentedon Sep 11, 2026
I would like to work on this one:
lib/Handler/SignEngine/SignEngineFactory.phptests/php/Unit/Handler/SignEngine/SignEngineFactoryTest.phpI 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.phpis already there and already uses a DataProvider, coveringpdf,PDF,odt,ODT,jpg,JPG,png,PNG,txtandTXTwithassertInstanceOf.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:ISignEngineHandler.My plan is to convert this test to a mocked
ContainerInterface, keep the extensions it already covers, addPdffrom 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 inSignFileService: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 callsgetCertificateChain(), which is on the interface, so it is unaffected.Widening three declarations in
SignFileServiceclears 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 overSignEngineFactory,SignFileService,PfxProviderandPdfSignatureDetectionServicebefore and after, and the only difference against the unmodified branch is one informational issue, described next.What that informational issue tells us
It is informational at
errorLevel="5", so it does not fail CI, and it is honest rather than accidental:PfxProvider::getOrGeneratePfx()declaresSignEngineHandlerand calls three methods that are not part ofISignEngineHandler: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:
SignEngineFactory::resolve()returnsISignEngineHandler; thematchand the container lookups stay byte-for-byte the same.SignFileServicelisted above widen toISignEngineHandler, so psalm stays green. Nothing else in that file changes.SignEngineFactoryTestmoves to a mocked container and gains the instance-identity, container-request andISignEngineHandlerassertions.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.PfxProviderstays as it is. Making it accept the interface would require adding those three certificate methods toISignEngineHandler, 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.
SignFileServiceis 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 insideSignEngineFactoryand 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.
maia-andre commentedon Sep 11, 2026
Opened #8347 with the plan above.
It follows the minimal variant: the factory return type, the three declarations in
SignFileServicethat carry the resolved engine, and the factory test converted to a mocked container. Nothing on your "do not change" list was touched, andPfxProviderwas left alone.Local results, in the devcontainer:
MissingDependencyerrors as the unmodified branch, no new errorSignEngineFactoryTestSignFileServiceTest+PfxProviderTest+PdfSignatureDetectionServiceTestphp-cs-fixeron the three changed filesThe 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.refactor(sign-engine): return the sign engine interface from the factory