LTV health check over Connect (Enterprise B-LT / B-LTA)

LTV health check over Connect (Enterprise B-LT / B-LTA)

At a glance

This recipe inspects the long-term-validation (LTV) material embedded in a signed PDF: certificate chains, revocation data (certificate revocation lists (CRL) / Online Certificate Status Protocol (OCSP)), and time-stamp tokens. You run the LTV health-check tool over the Connect transports. Long-term validation is an Enterprise-only capability. The tool is Enterprise-tier: a class_exists() probe discovers it, and it registers only when nextpdf/premium is installed alongside the server. It does not exist in a Pro or open-source-only install.

Level boundary (non-negotiable). PAdES B-T, B-LT, and B-LTA are distinct levels and are never collapsed:

• B-T is B-B plus a signature time-stamp. It does not add a document security store, validation-related information, or an archive time-stamp. B-T is the highest level available outside Enterprise.
• B-LT / B-LTA add validation material (DSS / VRI) and, for B-LTA, an archive time-stamp. These are Enterprise-only and are the subject of this recipe.

LTV data in a document is a capability the document carries. It is not a guarantee that the signature stays valid indefinitely. Whether a signature validates at a future date depends on the completeness and freshness of that material, and on the verifier’s policy at that time. Both are outside the library.

Install

composer require nextpdf/server

Confirm that the Enterprise LTV tool is present with a tools/list call; see /connect/tool-catalog/. If it is absent, this deployment is not Enterprise, and the LTV capability is not available. That is the intended tier boundary, not a defect.

Conceptual overview

The long-term-validation profile adds validation material beyond the baseline signature levels: a document security store and validation-related information (ETSI EN 319 142-2 §6.3.1). The PAdES baseline levels are distinct. B-T adds a signature time-stamp. B-LT/B-LTA add validation material and an archive time-stamp (ETSI EN 319 142-2 §5.5). A document security store holds material added by later revisions. Its presence is a structural fact, not a proof of validity by itself (ISO 32000-2 §12.8).

A “healthy” verdict therefore means the inspected LTV material is present and internally consistent at check time. It does not mean the signature will validate at an arbitrary future date.

API surface

Verify tool names against the running registry with tools/list; the catalog of record is /connect/tool-catalog/. This recipe does not restate a tool count.

Code sample — Quick start

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "ltv_health_check",
    "arguments": { "document_id": "<id>" }
  }
}

Code sample — Production

curl -sS -X POST https://connect.example.com/v1/tools/ltv_health_check \
  -H 'Authorization: Bearer '"$NEXTPDF_CONNECT_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"source":"/var/lib/nextpdf/archive/signed-report.pdf"}' \
  -o /tmp/ltv.json -w '%{http_code}' > /tmp/ltv-status || {
    echo "transport failure invoking ltv_health_check" >&2; exit 1; }

For each signature, the response reports the certificate chain and its embedding status, revocation information (CRL/OCSP presence and validity windows), the time-stamp token, and a warnings list that names missing or expired material. Use the warnings to decide which material to refresh. Treat a “healthy” result as “consistent at check time”, not “valid forever”.

Edge cases & gotchas

• No signatures. The tool returns a no-signatures error. Sign the document first.
• No document security store. A “no DSS” result means the document was signed without LTV material. It is at most a B-T-or-lower document, not B-LT/B-LTA. Re-signing with the Enterprise LTV path adds the material.
• Expired revocation data. A “degraded” verdict with warnings means the embedded CRL/OCSP has expired. You must embed fresh material again.
• Tool absent. Without nextpdf/premium, the Enterprise LTV tool is not registered. A Pro deployment can produce B-T, but it cannot produce or inspect B-LT/B-LTA material. That is the tier boundary.

Performance

The frontmatter budget is a documentation cap, not a service-level guarantee.

Security notes

Data Residency & PII Mitigations

The tool reads embedded certificate and revocation material. It does not fetch fresh material over the network as part of the check. Refreshing LTV material is a separate, deliberate operation.

Threat model

Avoid treating “LTV data present” as “signature valid indefinitely”. Present data is a capability. Its sufficiency depends on the verifier’s policy and on whether the material covers the full chain and remains unexpired. The library cannot promise any of these for a future date.

FIPS-mode behavior

The check parses embedded material and performs no signing operation. A Federal Information Processing Standards (FIPS)-mode policy on the host does not change its behavior.

Conformance

Claim	Clause	reference_id
LTV adds validation material (DSS/VRI) beyond baseline levels	ETSI EN 319 142-2 §6.3.1
B-T ≠ B-LT ≠ B-LTA; levels are distinct	ETSI EN 319 142-2 §5.5
A document security store’s presence is structural, not a validity proof	ISO 32000-2 §12.8

Support for an LTV health check does not certify that a signature is legally valid now or in the future. An independent validator makes that determination under its own policy.

Commercial context

Long-term validation (PAdES B-LT / B-LTA) is an Enterprise-only capability. The LTV health-check tool registers only when nextpdf/premium is installed alongside the server. PAdES B-T is the highest level available outside Enterprise and does not include DSS / VRI or an archive time-stamp.

Connect specifics

Transport availability (MCP / REST / gRPC)

Invoke the tool the same way over MCP tools/call, the REST tool endpoint, and the gRPC service through the shared tool executor.

HITL risk tier

The check is read-only and is not approval_required by default. An operator override may only raise its risk level. See /connect/hitl-risk-tiers/.

Confirmation gate JSON envelope

The tool does not trigger the gate unless an operator override raises it to approval_required. The envelope and single-use token contract is in /connect/hitl-risk-tiers/.

See also

• /cookbook/connect/forensic-analysis/ — revision-history analysis of signed documents.
• /cookbook/connect/compliance-check/ — named-standard validation.
• /connect/tool-catalog/ — per-tier tool set computation.
• /connect/hitl-risk-tiers/ — the risk model and the gate.