How to Handle Encrypted and Password-Protected PDFs with LiteParse: A Complete Guide

LiteParse handles encrypted PDFs by passing an optional password string through the LiteParseConfig to PDFium's FPDF_LoadDocument API, returning PasswordRequired or InvalidPassword errors when authentication fails.

Working with sensitive documents often requires parsing PDFs secured with encryption or password protection. The run-llama/liteparse repository provides first-class support for handling encrypted and password-protected PDFs with LiteParse across all language bindings and CLI interfaces. By leveraging the underlying PDFium library's native password capabilities, LiteParse exposes a unified configuration pattern that propagates authentication credentials from user input through to the document loading stage.

Understanding the Password Flow Architecture

LiteParse implements a three-tier architecture for password handling that ensures consistency whether you use the Rust core directly or higher-level language bindings.

Configuration Structure in config.rs

The password handling begins at the configuration layer. In crates/liteparse/src/config.rs, the LiteParseConfig struct defines pub password: Option<String> as a top-level optional field. When users supply a password via CLI flags, API parameters, or binding options, LiteParse stores it in this configuration object before any document processing begins.

PDF Loading Pipeline

When the parser initiates document processing, the extract::load_document_from_input helper in crates/liteparse/src/parser.rs forwards self.config.password.as_deref() (converting the Option<String> to Option<&str>) downstream to the PDFium wrapper. This ensures the password travels with the document request without requiring separate authentication steps.

PDFium Integration

The actual decryption occurs in crates/pdfium/src/library.rs, where pdfium::Pdfium::load_document (and load_document_from_bytes) forwards the optional password pointer to the native C function FPDF_LoadDocument. If no password is supplied, LiteParse passes a null pointer to PDFium, triggering the standard encrypted PDF behavior.

Error Handling for Authentication Failures

When encountering encrypted documents, LiteParse provides explicit error types defined in crates/pdfium/src/error.rs. The system returns PdfiumError::PasswordRequired when attempting to open a password-protected PDF without supplying credentials, or PdfiumError::InvalidPassword when the provided password fails to decrypt the document. These errors propagate up to the caller, allowing applications to implement retry logic or user prompts rather than failing silently.

Cross-Platform Implementation Examples

LiteParse exposes password functionality consistently across its Rust core, CLI tool, Node.js package, and Python bindings.

Command Line Interface

The Rust binary in crates/liteparse/src/main.rs exposes a --password flag that populates LiteParseConfig before processing:

liteparse input.pdf --output json --password "mySecret123"

Node.js and TypeScript

The Node.js wrapper in packages/node/src/lib.ts accepts a password option in the constructor:

import { LiteParse } from "liteparse";

const parser = new LiteParse({
  password: "mySecret123",
  output: "json"
});

const result = await parser.parseFile("encrypted.pdf");
console.log(result);

Python API

The Python binding in packages/python/liteparse/parser.py maps the password argument to the underlying Rust configuration:

from liteparse import LiteParse

parser = LiteParse(password="mySecret123", output="json")
result = parser.parse_file("encrypted.pdf")
print(result)

Direct Rust API

For Rust developers using the core library directly:

use liteparse::{LiteParse, LiteParseConfig};

let cfg = LiteParseConfig {
    password: Some("mySecret123".to_string()),
    ..Default::default()
};

let parser = LiteParse::new(cfg);
let result = parser.parse_path("encrypted.pdf")?;

Conversion and Rendering Support

Beyond basic parsing, LiteParse extends password support to document transformation workflows. The conversion utilities in crates/liteparse/src/conversion.rs and rendering functions in crates/liteparse/src/render.rs both accept the same Option<&str> password argument. This enables encrypted PDFs to undergo OCR processing, image rendering, or format conversion without requiring intermediate decryption steps.

Summary

LiteParse provides comprehensive support for password-protected PDFs by leveraging PDFium's native encryption handling:

• Configuration-driven: The LiteParseConfig struct stores passwords as Option<String> for optional security
• PDFium integration: Direct forwarding to FPDF_LoadDocument ensures reliable decryption
• Explicit errors: PasswordRequired and InvalidPassword errors enable proper error handling
• Universal support: Available in CLI, Node.js, Python, and Rust APIs with identical behavior
• Extended workflows: Passwords propagate through rendering and conversion pipelines

Frequently Asked Questions

What error does LiteParse return when a PDF password is incorrect?

LiteParse returns PdfiumError::InvalidPassword when the supplied password fails to decrypt the document, and PdfiumError::PasswordRequired when attempting to open an encrypted PDF without providing any password. These errors are defined in crates/pdfium/src/error.rs and propagate through all language bindings.

Can I use LiteParse to render encrypted PDFs to images?

Yes. The rendering functions in crates/liteparse/src/render.rs accept the same password argument as the parsing pipeline. Pass the password through your LiteParseConfig when initializing the parser, and LiteParse will decrypt the PDF before rendering pages to images.

Is password-protected PDF support available in the WASM build?

Yes. The WASM wrapper exposes the same password configuration options as the Node.js and Python bindings. The password field in the configuration object maps to the underlying Rust LiteParseConfig, ensuring consistent behavior across WebAssembly, native binaries, and language-specific packages.

How does LiteParse handle PDFs with owner passwords versus user passwords?

LiteParse delegates password validation entirely to PDFium's FPDF_LoadDocument implementation. Supply the appropriate password string through the configuration, and PDFium automatically handles the cryptographic verification regardless of whether the document uses owner passwords, user passwords, or both.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}