paperless-esig

paperless-esig is a third-party parser for Paperless-ngx. It adds support for EU electronically signed documents.

Supported formats

Paperless-ngx does not consume these files by default. The parser is required for them.

What the parser does

• Stores the original file unchanged. This is required for legal compliance.
• Extracts the signed PDF as the display and archive rendition. Browsers cannot render ZIP containers. A PAdES PDF is already a rendition and keeps its signature.
• Extracts the text of the PDF for search.
• Sets the document date from the signature signing time, with fallbacks to the PAdES /M field and the PDF creation date.
• Displays signature metadata in the metadata tab: signer name, organisation, country, signing time, certificate chain and issuer, RFC 3161 timestamp authority, and OCSP presence.
• Verifies the document digest and the signature value offline.
• Handles nested containers (an EDOC inside an EDOC, as produced by the Latvian e-archive) and multi-document containers (multiple PDFs and office documents merged into a single rendition).
• Assigns the signer as the document's correspondent. This happens after consumption, only when no correspondent was determined by content matching or workflow rules. The signer (organisation preferred over common name) is looked up case-insensitively and created if it does not exist, and the document is re-indexed so the correspondent is searchable immediately. This is enabled by default. Disable it with PAPERLESS_ESIG_ASSIGN_SIGNER_AS_CORRESPONDENT=false. Known limitations: the assignment is not recorded in the audit log, and the UI may show the new correspondent as "Private" until the page is reloaded.

Install

The parser runs inside Paperless-ngx. Use one of two methods.

Method 1: Docker

1. Clone this repository and build the image:

   docker build -t paperless-ngx-esig .
   

2. In docker-compose.yml, replace the webserver image with your build:

   services:
     webserver:
       image: paperless-ngx-esig
       # ...everything else stays the same
   

3. Restart the stack:

   docker compose up -d
   

Method 2: Bare metal

Install the package into the same virtual environment that runs Paperless-ngx:

uv pip install paperless-esig

Verify the install

1. Start Paperless-ngx and check the logs. Look for a line like this:

   [paperless.parsers.registry]   [third-party] Paperless-ngx ESig Parser v0.3.0 — https://github.com/Exerra/paperless-esig
   

   If the logs say No third-party parsers discovered. instead, see Troubleshooting.

2. Upload an .edoc, .asice, .bdoc, .adoc, or .p7m file, or a PAdES-signed PDF. The document is consumed, displays the inner PDF, and shows signature metadata in the metadata tab.

Limitations

• Documents are stored with the MIME type that libmagic reports. ASiC-E containers are stored as application/zip and CAdES files as application/octet-stream. The original file extension (.edoc, .asice, .p7m, and so on) is preserved in the stored filename.
• Plain ZIP files pass API and mail upload validation but are rejected during consumption with an "Unsupported mime type" error. The parser cannot inspect a file at validation time. ZIP files placed in the consume directory are attempted instead of silently skipped. The same applies to application/octet-stream files: CAdES signatures are the only octet-stream files that are consumed.
• Detached .p7s signatures are detected but rejected during parsing. They carry no document, so there is nothing to display or search.
• Office documents (DOCX, ODT, and similar) inside a container are converted to PDF by Gotenberg, and their text is extracted by Tika, when those services are configured with PAPERLESS_TIKA_ENDPOINT. Without them, the DOCX text is still extracted locally and the affected pages are omitted from the rendition.

Requirements

• Paperless-ngx 2.x. The parser uses the paperless_ngx.parsers entrypoint registry.
• The container must contain a PDF. Containers without a PDF cannot be ingested.

Troubleshooting

• No third-party parsers discovered. in the logs. The package is not installed in the environment that Paperless-ngx runs in. For Docker, check that your compose file points at the image you built (docker images).
• uv: command not found. Install uv first. Alternatively, python3 -m pip install . works.
• Plain ZIP files are rejected with "Unsupported mime type". This is expected. See Limitations.

License

GPL-3.0-or-later. Derived from the Paperless-ngx project, which is GPL-3.0.

For developers

docker build -t paperless-ngx-esig .

docker build --build-arg ESIG_VERSION=0.3.0 -t paperless-ngx-esig .

docker build --build-arg ESIG_SOURCE=local -t paperless-ngx-esig .

docker build --build-arg PAPERLESS_VERSION=2.14.7 -t paperless-ngx-esig .

git clone https://github.com/Exerra/paperless-esig.git
cd paperless-esig
uv sync
git clone --depth 1 https://github.com/paperless-ngx/paperless-ngx.git ../paperless-ngx

PYTHONPATH=../paperless-ngx/src uv run pytest

uv run ruff check src tests

uv build