Repository navigation
Description
This is part of #8335.
LibreSign is adding support for digital signatures where the private key stays outside LibreSign.
The PDF/PAdES side is handled separately by #8354.
The next boundary to define is the component that owns or accesses the private key and performs the cryptographic signing operation.
This may later include:
- a CSC remote signing service;
- an ICP-Brasil PSC;
- another HSM-backed signing service;
- a local-device signing bridge;
- another future signing mechanism where LibreSign does not own the private key.
Before implementing the first remote signing integration, we need a common architecture that does not make PDF/PAdES, CSC, OAuth or another specific protocol part of the shared signing domain.
Note
This issue is for architecture and domain design.
It does not require a production-code pull request. Implementation should be handled through focused follow-up issues after these decisions are clear.
Goal
Define the common architecture LibreSign will use when the private-key operation happens outside LibreSign.
The result should be precise enough that future CSC, ICP-Brasil PSC and other integrations can be implemented without requiring each contributor to invent a different domain model.
The design must define:
- the difference between an external signer integration and a signing credential;
- which capabilities LibreSign needs to know;
- how authorization fits the signing lifecycle;
- what cryptographic information is sent for the private-key operation;
- what result comes back;
- what belongs to the common signing boundary;
- what must remain specific to each protocol or integration;
- how remote signing and future local-device signing can use the same core boundary.
Common boundary
The common signing boundary sits between LibreSign signing orchestration and the component that can use the private key.
flowchart LR
O["LibreSign signing orchestration"]
O --> S["External signer integration"]
S --> C["Credential discovery"]
S --> A["Authorization when required"]
S --> K["Private-key operation"]
K --> R["Signature result"]
E["PDF / CMS / PAdES engine"] -. "separate responsibility" .-> O
The external signer integration must not process PDF or PAdES structures.
It receives the cryptographic operation prepared by the signing layer and returns the result of the private-key operation.
Integration and credential are different concepts
The architecture must distinguish the integration from the credential used to sign.
External signer integration
An external signer integration represents the mechanism LibreSign uses to access one or more external signing credentials.
Examples may include:
CSC service
ICP-Brasil PSC
HSM-backed signing service
future local-device signing bridge
One integration may expose zero, one or many credentials to a user.
The common model must not assume:
one integration = one certificate
or:
one user = one external credential
How integrations are configured, stored or assigned is outside this issue.
Credential
A credential represents a signing identity/key available through an external signer integration.
It may expose information LibreSign needs for the signing operation, such as:
- an identifier;
- public signer certificate information;
- supported cryptographic algorithms;
- relevant signing capabilities;
- human-readable information needed to select the credential.
For remote signing, the private key must never become part of the LibreSign credential model.
Protocol-specific identifiers and metadata may exist, but they should not become part of the common domain unless LibreSign actually needs them outside that protocol implementation.
Capabilities
LibreSign needs enough information to determine whether a credential can perform the cryptographic operation prepared by the signing layer.
The architecture must define which capabilities are common across integrations.
These may include:
- supported digest algorithms;
- supported signature algorithms;
- required algorithm parameters;
- authorization requirements;
- public certificate information required by the signing engine.
Do not derive the common model only from CSC terminology.
The same model must be checked against ICP-Brasil PSC requirements.
Protocol-specific capabilities that LibreSign does not need outside the integration should remain internal to that implementation.
Authorization
Some external signing mechanisms require user authorization before the private key can be used.
Possible mechanisms include:
- OAuth-based authorization;
- redirects;
- OTP;
- PIN confirmation;
- another authentication or authorization mechanism.
The common architecture must support a lifecycle conceptually similar to:
select credential
-> authorize when required
-> perform private-key operation
Authorization may be synchronous or asynchronous.
The shared domain must not assume that authorization always means:
- OAuth;
- a browser redirect;
- an access token;
- OTP;
- any specific CSC mechanism.
The common architecture should represent the lifecycle and state that LibreSign needs to coordinate.
Protocol-specific authorization details must remain inside the concrete integration.
Cryptographic signing operation
The external signer integration must receive only the cryptographic information required to perform the private-key operation.
Conceptually:
prepared signing operation
-> external signer integration
-> private-key operation
-> signature result
The final common representation must be compatible with the real PDF/PAdES external-signing lifecycle implemented by #8354.
Do not assume in advance that every signing operation can be represented only by:
document hash
or one arbitrary:
signature algorithm
The model must be able to carry the digest, signature algorithm and required parameters established by the real signing implementation.
The external signer integration must not need to know why that cryptographic input exists or how it relates to PDF, CMS or PAdES.
Responsibility boundary
The external signer side may be responsible for:
- discovering available signing credentials;
- exposing the capabilities LibreSign needs;
- obtaining public signer certificate information;
- performing integration-specific authorization;
- communicating with the remote service or local bridge;
- performing the private-key operation;
- translating between the common LibreSign signing operation and the integration-specific protocol;
- returning the cryptographic signature result.
It must not be responsible for:
- PDF parsing;
- PDF incremental updates;
ByteRange;- CMS/PAdES construction;
- signed PDF attributes;
- PDF signature fields;
- visible signature elements;
- DocMDP or FormMDP;
- timestamp or LTV document processing;
- LibreSign workflow status;
- SignRequest business rules;
- provider assignment;
- policy evaluation;
- administration UI.
These responsibilities belong to other layers.
Remote protocol implementations
Remote signing is the first target.
The architecture should allow concrete implementations such as:
Remote signing provider
├── CSC
├── ICP-Brasil PSC
└── future remote provider types
A different company using the same supported standard should normally not require a different protocol implementation.
For example, standards-compliant CSC services should share the same CSC implementation and differ through configuration.
Provider-specific behavior should require a dedicated implementation only when it cannot be represented correctly by the supported standard adapter.
The same principle should apply to ICP-Brasil PSC.
Future local-device signing
HTTP, OAuth and remote-service concepts must not become requirements of the common external signing boundary.
A future local-device flow may look like:
LibreSign
-> browser integration
-> native bridge
-> smart card / token / operating-system certificate
From LibreSign signing orchestration, the core responsibility remains:
receive cryptographic signing operation
-> use external private key
-> return signature result
The browser/native implementation itself is outside this issue.
This issue only needs to ensure that the common architecture does not prevent that future integration or require changes to the PDF/PAdES layer.
Configuration, assignment and policy are separate
External signer runtime behavior must remain separate from:
- configuration persistence;
- provider secrets;
- administration APIs;
- assignment to users or groups;
- policy evaluation.
Those concerns will be designed separately when their implementation is needed.
The common signing domain should not depend on how configuration or assignment data is stored.
Secrets must not become part of normal signer or credential metadata exposed to callers.
Relationship with #8354
#8354 defines the real PDF/PAdES external-signing lifecycle.
This architecture must consume the cryptographic operation produced by that layer without depending on PDF/PAdES internals.
The final shape of the common signing operation must therefore be validated against the real implementation from #8354.
Do not create a competing cryptographic request model if #8354 already establishes the information that needs to cross this boundary.
This issue can progress in parallel with #8354, but it should not be considered complete until both sides are compatible.
Validate against CSC and ICP-Brasil PSC
CSC and ICP-Brasil PSC are expected to be the first remote consumers of this architecture.
Before closing this issue, review the current specifications of both ecosystems and verify that the proposed common model can represent what LibreSign needs.
The common domain must not use CSC-specific or ICP-Brasil-specific names for concepts that are actually generic.
Protocol-specific concepts should remain inside their respective integrations.
Important differences between CSC and ICP-Brasil PSC that affect the common architecture should be documented in this issue.
No speculative production code
Do not add production code only to reserve architecture for future work.
In particular, this issue should not add:
- interfaces without a real production implementation;
- reusable fake integrations;
- empty registries;
- credential DTOs without a production consumer;
- managers without real callers;
- placeholder CSC or PSC implementations.
Production abstractions should be introduced together with the first real implementation that requires them.
Architecture decisions can be documented directly in this issue.
Expected outcome
Before this issue is closed, the agreed design must answer:
- What represents an external signer integration?
- What represents a signing credential?
- Which capabilities must LibreSign know?
- What cryptographic information crosses the signing boundary?
- What does the external signer return?
- How do synchronous and asynchronous authorization fit the lifecycle?
- Which authorization state belongs to the integration and which belongs to the future signing session?
- Which concepts are common between CSC and ICP-Brasil PSC?
- Which concepts must remain protocol-specific?
- How can future local-device signing use the same core boundary?
- Where does integration runtime behavior stop and configuration begin?
- Where do assignment and policy responsibilities live?
These decisions should be recorded in this issue before implementation tasks that depend on them are opened.
Scope boundaries
Please keep this issue focused on architecture.
Do not:
- add production signing-provider abstractions;
- implement CSC;
- implement ICP-Brasil PSC;
- implement a local-device bridge;
- implement PKCS#11 communication;
- add provider database entities;
- add provider configuration APIs;
- add provider assignment;
- add policy configuration;
- add signing-session persistence;
- change existing signing methods;
- add frontend changes;
- add OAuth endpoints;
- implement PDF/PAdES logic.
Concrete implementation belongs in focused follow-up issues after the required decisions are clear.
Why this helps #8335
PDF/PAdES processing and access to the private key are separate responsibilities.
Without a common external-signing architecture, each integration could independently invent its own concepts for:
credential
authorization
capabilities
algorithm selection
signing operation
signature result
That would make CSC, ICP-Brasil PSC and future integrations harder to share and maintain.
Defining this boundary before the first provider implementation allows LibreSign to support multiple signing ecosystems without coupling remote protocols to PDF/PAdES or to one specific standard.
Done when
- External signer integration and credential have clear and separate meanings.
- Common external signer responsibilities are defined.
- PDF/PAdES responsibilities are explicitly outside this layer.
- Required credential and cryptographic capabilities are defined.
- Synchronous and asynchronous authorization flows fit the architecture.
- The cryptographic signing operation is compatible with the real external PDF lifecycle from Implement the external PDF signing lifecycle #8354.
- Current CSC requirements have been checked against the proposed model.
- Current ICP-Brasil PSC requirements have been checked against the proposed model.
- Protocol-specific concepts that must remain outside the common domain are documented.
- Future local-device signing can fit the same architectural boundary without making remote HTTP concepts universal.
- Configuration, assignment and policy remain separate concerns.
- No speculative production code is added by this issue.
- The first concrete remote provider issue can be written without requiring its contributor to redesign the common domain.
Metadata
Metadata
Assignees
Labels
Type
Fields
Priority
Projects
- StatusShow more project fields0. Backlog
Activity
[-]Define the remote signing provider architecture[/-][+]Define the external signing provider architecture[/+]rodrigodev commentedon Oct 24, 2026
Following the external PDF lifecycle work in [#9216](#9216), I’d like to agree on the provider boundary before starting a concrete integration.
I checked the relevant signing and authorization sections of CSC API v2.2.0.0, its referenced Data Model v1.0.0, and DOC-ICP-17.01 v3.0. The proposal below is for architecture review; production abstractions would arrive with the first real implementation.
Proposed boundary
The integration receives the cryptographic payload without needing the PDF service’s opaque preparation state.
For the current lifecycle, that payload contains a precomputed digest of CMS signed attributes. It must not be treated as the uploaded document’s hash or hashed again.
Findings affecting the design
CSC v2.2 distinguishes service authorization from credential authorization (§8.1). These are separate responsibilities, although one authorization grant can cover both.
Authorization can itself be asynchronous through
credentials/authorizeCheck. Signing can independently be asynchronous throughsignatures/signHash, returning aresponseIDretrieved throughsignatures/signPolling(§§11.9, 11.13, 11.15). Our lifecycle therefore needs to distinguish waiting for authorization from waiting for a signature.CSC also supports authorization using a signature qualifier, with the credential resolved during authorization. Consequently, “select an existing credential, then authorize” should be our initial supported flow, rather than a universal rule.
The current #8354 preparation requires the signer certificate upfront. Supporting dynamically created or subsequently resolved credentials would need a separately validated sequence that obtains the certificate before final PDF preparation.
Cryptographic input and authorization context are related but distinct. CSC advertises supported authorization hash types and can require document-related authorization information. A provider’s support for
signHashalone does not establish compatibility with our complete authorization flow.For ICP-Brasil PSC, the proposed mapping is
/oauth/signatureusingRAW, because #8354 constructs CMS locally. Exact algorithm and signature-encoding behavior still requires testing against the selected provider.Decisions requested
Cryptographic contract: Can we reuse Implement the external PDF signing lifecycle #8354’s existing payload, extending it when a real operation requires additional algorithm parameters, rather than creating a competing request model?
Initial scope: Can the first integration target one signing operation using a credential whose certificate is available before preparation? Credential creation/deletion, short-lived credential provisioning and batch authorization would remain follow-up work.
Authorization compatibility: Can we require each adapter to establish that its supported authorization flow accepts the prepared operation’s representation? Any additional consent information should have an explicit source and contract; the adapter should not reconstruct PDF/CMS structures.
State ownership: Can the future signing session own the actor, selected credential, expected certificate, exact payload, trusted prepared state, document revision and expiry, while the integration owns protected protocol state and exposes a continuation reference?
Resumable outcomes: Can the common lifecycle represent interaction required, authorization pending, signing pending, signature available, rejection, expiry, failure and an unknown outcome requiring reconciliation? A timeout after submission must not automatically trigger another private-key operation.
Capabilities: Can compatibility be evaluated as a supported combination of input type, digest, signature algorithm, required parameters, output encoding and authorization requirements?
First implementation: Which protocol/provider should we validate first, ideally with sandbox access?
Protocol-specific identifiers, tokens, activation data, endpoint discovery and transport encoding remain inside adapters. Configuration persistence, assignment and policy remain separate concerns.
A future local-device bridge should consume the same cryptographic operation and return the same signature result, using its own discovery and authorization mechanisms.
Once these decisions are agreed, we can record them here and scope the first adapter and the session/orchestration work as focused implementation tasks.
fix(tools): bounded process exchange and conservative outcome handlin…
fix(tools): interleaved bounded exchange, confirmed termination, hone…
fix(tools): honest unconfirmed-termination guarantee and proof-specif…
fix(tools): pidfile-based watchdog cleanup and committed reproducible…
vitormattos commentedon Oct 31, 2026
Thanks for the detailed analysis. I agree with the proposed boundary: LibreSign owns workflow orchestration and signing-session state, the PDF signing engine owns CMS/PAdES preparation and finalization, and provider adapters own credential access, authorization and the private-key operation.
For the first implementation, let's keep the scope narrow:
I also think we should account for international interoperability now, without putting country-specific legislation into the common interface. CSC is a protocol boundary; requirements such as eIDAS qualification, European Trusted Lists and ICP-Brasil trust rules belong in their respective integration and validation work. We already track these next steps in #8942–#8944.
Would you be interested in helping define or validate the first CSC integration? If you have access to a provider sandbox, particularly one relevant to Portugal or the wider EU, that would be very useful.
Organizations interested in funding or piloting this integration are also welcome. We can discuss that separately from the technical design.
vitormattos commentedon Nov 4, 2026
Following the previous discussion and a review of the current SignerPHP repositories, I'd like to consolidate the architectural direction and clarify the seven decisions.
Our goal is to make LibreSign extensible across signing ecosystems: cloud certificates, CSC-compatible services, ICP-Brasil, A3/hardware certificates, European trust services, and future country-specific integrations.
The architecture should build on SignerPHP rather than introduce a parallel signing or provider framework inside LibreSign.
Responsibility boundaries
The existing SignerPHP contracts should be our starting point. We should extend them only when a real integration demonstrates a missing capability, rather than creating equivalent LibreSign interfaces in advance.
Decisions on the seven questions
Cryptographic contract: Reuse SignerPHP's
ExternalSigningPayloadand preparation/completion contracts, preserving the exact input type, digest, signature algorithm, encoding and any required parameters. Do not rehash prepared input or introduce a competing cryptographic representation.Initial scope: Start with one signing operation and a credential whose public certificate is available before PDF preparation. Credential provisioning, dynamically resolved credentials and batch operations remain separate follow-up work.
Authorization compatibility: Each adapter must establish that its authorization and signing mechanisms support the prepared cryptographic operation. Protocol-specific consent and authorization data remain within the corresponding integration. Adapters must not reconstruct PDF or CMS structures.
State ownership: LibreSign will own the authoritative signing session and its relationship to the signer, credential, document revision, prepared operation and expiry. Integration-specific credentials, tokens and authorization state must remain protected within the corresponding integration. The exact persistence and continuation mechanisms belong to the future session/orchestration implementation.
Resumable outcomes: Future orchestration must distinguish authorization pending, signing pending, completed, rejected, expired, failed and uncertain outcomes. An uncertain result must be reconciled before considering another private-key operation.
Capabilities: Compatibility must be determined from the complete supported combination of input representation, digest, signature algorithm, parameters, output encoding, certificate capabilities and authorization requirements. We should not assume every provider supports the same operation.
First integration: CSC remains our preferred standards-based starting point for LibreSign, subject to obtaining a suitable sandbox. SignerPHP's existing VIDaaS implementation and the IntegraICP v3 work provide useful experience and reusable components, but do not establish CSC interoperability by themselves.
Future interoperability
The LibreSign administrator should eventually be able to configure supported signing integrations and determine which methods are available according to instance policy. The signer must still use an authorized credential and complete the corresponding consent or authorization flow.
The architecture must also accommodate services that do not return a raw cryptographic signature. Such cases require a separately validated completion contract; we should not force every national identity or signing service into an incompatible interface.
Likewise, eIDAS trust requirements and country-specific certificate validation should remain separate from the common cryptographic contract.
Scope of #9216
This PR should remain focused on the internal, resumable PDF signing lifecycle. It must not introduce provider configuration, session persistence, OAuth, administrative interfaces or other future integrations.
Before defining the next implementation tasks, we should review the existing SignerPHP contracts, validate a concrete provider against them, and then introduce only the additional abstractions required by that implementation.
This preserves the current contribution's scope while keeping the path open for the broader external-signing roadmap.