Security

This guide covers the VerifyKit SDK's security model, data handling, trust architecture, and recommendations for secure deployment.

Trust Model

VerifyKit is a client-side PDF signature verification library. All cryptographic operations run entirely in the browser (or in Node.js), with no data sent to external servers by default.

• No server-side processing. PDF bytes are never uploaded to a remote server for verification. All parsing, hash computation, and certificate chain validation happen locally.
• WASM sandbox. The core verification engine is compiled to WebAssembly and runs inside the browser's WASM sandbox, which provides memory isolation from the host page.
• Deterministic results. Given the same PDF and trust store, verification results are identical across environments.

Data Handling

PDF Bytes Stay Local

When a user loads a PDF into VerifyKit (via useVerification().load(), verifier.verify(), or the viewer UI), the file bytes remain in browser memory. They are:

• Read into an ArrayBuffer or Uint8Array
• Passed to the WASM engine for signature extraction and validation
• Optionally passed to PDF.js for rendering

At no point are the PDF bytes transmitted over the network. When the viewer is destroyed or the page is closed, the memory is released.

No Telemetry or Analytics

The SDK does not collect usage data, telemetry, or analytics. There are no outbound network requests initiated by the SDK itself, with the following exceptions:

• AIA (Authority Information Access): When enableAIA is true (the default), the verifier may fetch missing intermediate certificates from URLs embedded in the certificate chain. Disable this with enableAIA: false.
• Revocation checking: When the @trexolab/verifykit-plugin-revocation plugin is installed, OCSP and CRL requests are made via a server-side proxy to check certificate revocation status.
• PDF.js worker: The worker script is loaded from the URL you provide via workerUrl.

WASM Security

The verification engine is compiled from Rust to WebAssembly. This provides several security properties:

• Memory isolation. WASM modules operate in a linear memory sandbox. They cannot access the host page's JavaScript heap, DOM, or other browser APIs directly.
• No file system access. The WASM module can only process data explicitly passed to it via the JavaScript API.
• No network access. The WASM module cannot make network requests. All network operations (AIA, revocation) are handled by the JavaScript layer.
• Type safety. The Rust source code provides memory safety guarantees that carry through to the compiled WASM output.

WASM Loading

As of v0.3.1+, the WASM binary is base64-embedded in the JavaScript bundle. No external .wasm file needs to be served. If you use wasmUrl to load WASM from a custom location, ensure the file is served over HTTPS and from a trusted origin.

Certificate Trust Store

VerifyKit ships with a built-in trust store containing 119 Adobe Approved Trust List (AATL) root CA certificates, along with Indian PKI and international certificate authorities. These cover the most widely used certificate authorities for document signing.

Trust Store Modes

const verifier = await createVerifier({
  trustStore: {
    certificates: [pemString],
    mode: 'merge',
  },
})

When to Use a Custom Trust Store

• Enterprise CAs: If your organization uses an internal CA for document signing, add the root certificate via mode: 'merge'.
• Restricted environments: If you want to trust only specific CAs (e.g., a national eID CA), use mode: 'replace' with just those root certificates.

Revocation Proxy Security

The @trexolab/verifykit-plugin-revocation plugin performs online certificate revocation checking (OCSP and CRL). Because browsers block direct OCSP/CRL requests due to CORS, the plugin routes these requests through a server-side proxy.

SSRF Protection

If you implement a revocation proxy endpoint, protect it against Server-Side Request Forgery (SSRF):

1. Allowlist target hosts. Only forward requests to known OCSP responder and CRL distribution point hostnames. Do not allow arbitrary URLs.
2. Validate URL schemes. Only permit http:// and https:// schemes. Reject file://, ftp://, and other protocols.
3. Block internal networks. Reject requests targeting private IP ranges (10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16, 127.0.0.0/8, ::1).
4. Set timeouts. Apply reasonable request timeouts (e.g., 10 seconds) to prevent resource exhaustion.
5. Rate limit. Apply rate limiting to the proxy endpoint to prevent abuse.

Content Security Policy

If your application enforces a strict Content Security Policy, add the following directives:

Content-Security-Policy:
  script-src 'self' 'wasm-unsafe-eval';
  worker-src 'self' https://unpkg.com;

If you self-host the worker file, worker-src 'self' is sufficient.

Compliance References

VerifyKit implements signature verification algorithms consistent with the following standards and regulations. These references are provided for informational purposes and do not constitute legal advice or certification claims.

• PAdES (ETSI EN 319 142): The SDK validates PAdES signatures at levels B-B, B-T, B-LT, and B-LTA. It parses CMS/PKCS#7 signature containers embedded in PDF documents per the PAdES specification.
• eIDAS (EU Regulation 910/2014): The trust store and certificate chain validation support verification of qualified electronic signatures issued under the eIDAS framework, provided the appropriate trust anchors are configured.
• ESIGN Act (US): VerifyKit can verify digital signatures that comply with the US Electronic Signatures in Global and National Commerce Act. The SDK does not impose jurisdiction-specific rules; it validates the cryptographic properties of the signature.
• PDF 2.0 (ISO 32000-2): Signature parsing follows the PDF specification for digital signature dictionaries, byte range coverage, and incremental update detection.

Recommendations

Keep Dependencies Updated

• Update @trexolab/verifykit-core and @trexolab/verifykit-react regularly to receive trust store updates and security patches.
• Pin pdfjs-dist to the version specified by VerifyKit to avoid compatibility issues.

Use HTTPS

• Serve your application over HTTPS to prevent man-in-the-middle tampering with the WASM module or PDF.js worker.
• If self-hosting the worker, serve it from the same origin over HTTPS.

Validate Proxy Endpoints

• If using the revocation plugin, ensure your proxy endpoint validates and sanitizes all input URLs.
• Apply authentication to the proxy endpoint if it is exposed on a public network.

Restrict Trust Stores in Sensitive Environments

• For high-assurance use cases, use mode: 'replace' with a curated set of trusted root certificates rather than the full built-in set.

Handle Verification Results Carefully

• Do not rely solely on overallStatus for security decisions. Inspect individual check results (integrityCheck, certificateChainCheck, revocationCheck, etc.) to understand the full picture.
• Log verification results for audit trails when required by your compliance framework.