feat: support encrypted PDF extraction

steipete · steipete · commit f74bc3fe3d23 · 2026-05-28T20:05:50.000+01:00
diff --git a/docs/tools/pdf.md b/docs/tools/pdf.md
@@ -53,6 +53,10 @@ Analysis prompt.
 Page filter like `1-5` or `1,3,7-9`.
 </ParamField>
 
+<ParamField path="password" type="string">
+Password for encrypted PDFs in extraction fallback mode.
+</ParamField>
+
 <ParamField path="model" type="string">
 Optional model override in `provider/model` form.
 </ParamField>
@@ -66,6 +70,7 @@ Input notes:
 - `pdf` and `pdfs` are merged and deduplicated before loading.
 - If no PDF input is provided, the tool errors.
 - `pages` is parsed as 1-based page numbers, deduped, sorted, and clamped to the configured max pages.
+- `password` applies to every PDF in the request and is only used by extraction fallback mode.
 - `maxBytesMb` defaults to `agents.defaults.pdfMaxBytesMb` or `10`.
 
 ## Supported PDF references
@@ -92,6 +97,7 @@ The tool sends raw PDF bytes directly to provider APIs.
 Native mode limits:
 
 - `pages` is not supported. If set, the tool returns an error.
+- `password` is not supported. Use a non-native model to analyze encrypted PDFs.
 - Multi-PDF input is supported; each PDF is sent as a native document block /
   inline PDF part before the prompt.
 
@@ -108,6 +114,7 @@ Flow:
 Fallback details:
 
 - Page image extraction uses a pixel budget of `4,000,000`.
+- Encrypted PDFs can be opened with the top-level `password` parameter.
 - If the target model does not support image input and there is no extractable text, the tool errors.
 - If text extraction succeeds but image extraction would require vision on a
   text-only model, OpenClaw drops the rendered images and continues with the
@@ -189,6 +196,17 @@ Page-filtered fallback model:
 }
 ```
 
+Encrypted PDF with extraction fallback:
+
+```json
+{
+  "pdf": "/tmp/locked.pdf",
+  "password": "example-password",
+  "model": "openai/gpt-5.4-mini",
+  "prompt": "Summarize this contract"
+}
+```
+
 ## Related
 
 - [Tools Overview](/tools) - all available agent tools
diff --git a/extensions/document-extract/document-extractor.test.ts b/extensions/document-extract/document-extractor.test.ts
@@ -108,6 +108,28 @@ describe("PDF document extractor", () => {
     expect(pdfDocument.destroy).toHaveBeenCalledTimes(1);
   });
 
+  it("opens encrypted PDFs with the request password", async () => {
+    pdfDocument.extract.mockResolvedValueOnce({ text: "enough text", images: [] });
+    const extractor = createPdfDocumentExtractor();
+
+    await extractor.extract(request({ password: "secret" }));
+
+    expect(openPdfMock).toHaveBeenCalledWith(expect.any(Uint8Array), { password: "secret" });
+    expect(pdfDocument.destroy).toHaveBeenCalledTimes(1);
+  });
+
+  it("normalizes clawpdf password errors", async () => {
+    openPdfMock.mockRejectedValueOnce(
+      Object.assign(new Error("bad password"), { code: "password" }),
+    );
+    const extractor = createPdfDocumentExtractor();
+
+    await expect(extractor.extract(request({ password: "wrong" }))).rejects.toThrow(
+      "PDF requires a password or password is incorrect.",
+    );
+    expect(pdfDocument.destroy).not.toHaveBeenCalled();
+  });
+
   it("filters selected pages before passing them to clawpdf", async () => {
     pdfDocument.extract
       .mockResolvedValueOnce({ text: "", images: [] })
diff --git a/extensions/document-extract/document-extractor.ts b/extensions/document-extract/document-extractor.ts
@@ -1,4 +1,4 @@
-import type { PdfEngine, PdfImage } from "clawpdf";
+import type { PdfDocument, PdfEngine, PdfImage } from "clawpdf";
 import type {
   DocumentExtractedImage,
   DocumentExtractionRequest,
@@ -33,11 +33,36 @@ function toDocumentImage(image: PdfImage): DocumentExtractedImage {
   };
 }
 
+function isPdfPasswordError(err: unknown): boolean {
+  return Boolean(err && typeof err === "object" && (err as { code?: unknown }).code === "password");
+}
+
+async function openPdfDocument(params: {
+  engine: PdfEngine;
+  input: Uint8Array;
+  password?: string;
+}): Promise<PdfDocument> {
+  try {
+    return params.password
+      ? await params.engine.open(params.input, { password: params.password })
+      : await params.engine.open(params.input);
+  } catch (err) {
+    if (isPdfPasswordError(err)) {
+      throw new Error("PDF requires a password or password is incorrect.", { cause: err });
+    }
+    throw err;
+  }
+}
+
 async function extractPdfContent(
   request: DocumentExtractionRequest,
 ): Promise<DocumentExtractionResult> {
   const engine = await loadPdfEngine();
-  const pdf = await engine.open(new Uint8Array(request.buffer));
+  const pdf = await openPdfDocument({
+    engine,
+    input: new Uint8Array(request.buffer),
+    ...(request.password ? { password: request.password } : {}),
+  });
   try {
     const pages = request.pageNumbers
       ? request.pageNumbers
diff --git a/src/agents/tools/pdf-tool.test.ts b/src/agents/tools/pdf-tool.test.ts
@@ -500,6 +500,22 @@ describe("createPdfTool", () => {
     });
   });
 
+  it("rejects password parameter for native PDF providers", async () => {
+    await withTempPdfAgentDir(async (agentDir) => {
+      await stubPdfToolInfra(agentDir, { provider: "anthropic", input: ["text", "document"] });
+      const cfg = withPdfModel(ANTHROPIC_PDF_MODEL);
+      const tool = requirePdfTool((await loadCreatePdfTool())({ config: cfg, agentDir }));
+
+      await expect(
+        tool.execute("t1", {
+          prompt: "summarize",
+          pdf: "/tmp/doc.pdf",
+          password: "secret",
+        }),
+      ).rejects.toThrow("password is not supported with native PDF providers");
+    });
+  });
+
   it("uses extraction fallback for non-native models", async () => {
     await withTempPdfAgentDir(async (agentDir) => {
       await stubPdfToolInfra(agentDir, { provider: "openai", input: ["text"] });
@@ -531,6 +547,58 @@ describe("createPdfTool", () => {
     });
   });
 
+  it("passes password to PDF extraction fallback", async () => {
+    await withTempPdfAgentDir(async (agentDir) => {
+      await stubPdfToolInfra(agentDir, { provider: "openai", input: ["text"] });
+      const extractSpy = vi.spyOn(pdfExtractModule, "extractPdfContent").mockResolvedValue({
+        text: "Encrypted content",
+        images: [],
+      });
+      completeMock.mockResolvedValue({
+        role: "assistant",
+        stopReason: "stop",
+        content: [{ type: "text", text: "fallback summary" }],
+      } as never);
+
+      const cfg = withPdfModel(OPENAI_PDF_MODEL);
+      const tool = requirePdfTool((await loadCreatePdfTool())({ config: cfg, agentDir }));
+
+      await tool.execute("t1", {
+        prompt: "summarize",
+        pdf: "/tmp/doc.pdf",
+        password: "secret",
+      });
+
+      expect(extractSpy).toHaveBeenCalledWith(expect.objectContaining({ password: "secret" }));
+    });
+  });
+
+  it("preserves PDF password whitespace before extraction fallback", async () => {
+    await withTempPdfAgentDir(async (agentDir) => {
+      await stubPdfToolInfra(agentDir, { provider: "openai", input: ["text"] });
+      const extractSpy = vi.spyOn(pdfExtractModule, "extractPdfContent").mockResolvedValue({
+        text: "Plain content",
+        images: [],
+      });
+      completeMock.mockResolvedValue({
+        role: "assistant",
+        stopReason: "stop",
+        content: [{ type: "text", text: "fallback summary" }],
+      } as never);
+
+      const cfg = withPdfModel(OPENAI_PDF_MODEL);
+      const tool = requirePdfTool((await loadCreatePdfTool())({ config: cfg, agentDir }));
+
+      await tool.execute("t1", {
+        prompt: "summarize",
+        pdf: "/tmp/doc.pdf",
+        password: " secret ",
+      });
+
+      expect(extractSpy).toHaveBeenCalledWith(expect.objectContaining({ password: " secret " }));
+    });
+  });
+
   it("adds Codex instructions for PDF extraction fallback requests", async () => {
     await withTempPdfAgentDir(async (agentDir) => {
       await stubPdfToolInfra(agentDir, {
@@ -615,6 +683,7 @@ describe("createPdfTool", () => {
     expect(props).toHaveProperty("pdf");
     expect(props).toHaveProperty("pdfs");
     expect(props).toHaveProperty("pages");
+    expect(props).toHaveProperty("password");
     expect(props).toHaveProperty("model");
     expect(props).toHaveProperty("maxBytesMb");
   });
diff --git a/src/agents/tools/pdf-tool.ts b/src/agents/tools/pdf-tool.ts
@@ -71,6 +71,7 @@ export const PdfToolSchema = Type.Object({
       description: 'Pages, e.g. "1-5", "1,3,5-7"; default all.',
     }),
   ),
+  password: Type.Optional(Type.String({ description: "Password for encrypted PDFs." })),
   model: Type.Optional(Type.String()),
   maxBytesMb: Type.Optional(Type.Number()),
 });
@@ -144,6 +145,7 @@ async function runPdfPrompt(params: {
   modelOverride?: string;
   prompt: string;
   pdfBuffers: Array<{ base64: string; filename: string }>;
+  password?: string;
   pageNumbers?: number[];
   getExtractions: () => Promise<PdfExtractedContent[]>;
 }): Promise<{
@@ -181,6 +183,11 @@ async function runPdfPrompt(params: {
       });
 
       if (providerSupportsNativePdf(provider)) {
+        if (params.password) {
+          throw new Error(
+            `password is not supported with native PDF providers (${provider}/${modelId}). Remove password, or use a non-native model for encrypted PDFs.`,
+          );
+        }
         if (params.pageNumbers && params.pageNumbers.length > 0) {
           throw new Error(
             `pages is not supported with native PDF providers (${provider}/${modelId}). Remove pages, or use a non-native model for page filtering.`,
@@ -356,6 +363,7 @@ export function createPdfTool(options?: {
 
       // Parse page range
       const pagesRaw = normalizeOptionalString(record.pages);
+      const password = typeof record.password === "string" ? record.password : undefined;
 
       const pdfModelConfig =
         registrationPdfModelConfig ??
@@ -486,6 +494,7 @@ export function createPdfTool(options?: {
             maxPages: configuredMaxPages,
             maxPixels: PDF_MAX_PIXELS,
             minTextChars: PDF_MIN_TEXT_CHARS,
+            ...(password ? { password } : {}),
             pageNumbers,
             config: options?.config,
           });
@@ -502,6 +511,7 @@ export function createPdfTool(options?: {
         modelOverride,
         prompt: promptRaw,
         pdfBuffers: loadedPdfs.map((p) => ({ base64: p.base64, filename: p.filename })),
+        ...(password ? { password } : {}),
         pageNumbers,
         getExtractions,
       });
diff --git a/src/media/document-extractors.runtime.ts b/src/media/document-extractors.runtime.ts
@@ -24,6 +24,7 @@ export async function extractDocumentContent(
     maxPages: params.maxPages,
     maxPixels: params.maxPixels,
     minTextChars: params.minTextChars,
+    ...(params.password ? { password: params.password } : {}),
     ...(params.pageNumbers ? { pageNumbers: params.pageNumbers } : {}),
     ...(params.onImageExtractionError
       ? { onImageExtractionError: params.onImageExtractionError }
diff --git a/src/media/pdf-extract.test.ts b/src/media/pdf-extract.test.ts
@@ -39,6 +39,31 @@ describe("extractPdfContent", () => {
     });
   });
 
+  it("passes PDF passwords through to document extractors", async () => {
+    extractDocumentContentMock.mockResolvedValue({
+      text: "encrypted pdf",
+      images: [],
+      extractor: "pdf",
+    });
+
+    await extractPdfContent({
+      buffer: Buffer.from("%PDF-1.4"),
+      maxPages: 2,
+      maxPixels: 100,
+      minTextChars: 10,
+      password: "secret",
+    });
+
+    expect(extractDocumentContentMock).toHaveBeenCalledWith({
+      buffer: Buffer.from("%PDF-1.4"),
+      mimeType: "application/pdf",
+      maxPages: 2,
+      maxPixels: 100,
+      minTextChars: 10,
+      password: "secret",
+    });
+  });
+
   it("throws a clear disabled error when no document extractor is available", async () => {
     extractDocumentContentMock.mockResolvedValue(null);
 
diff --git a/src/media/pdf-extract.ts b/src/media/pdf-extract.ts
@@ -13,6 +13,7 @@ export async function extractPdfContent(params: {
   maxPages: number;
   maxPixels: number;
   minTextChars: number;
+  password?: string;
   pageNumbers?: number[];
   config?: OpenClawConfig;
   onImageExtractionError?: (error: unknown) => void;
@@ -23,6 +24,7 @@ export async function extractPdfContent(params: {
     maxPages: params.maxPages,
     maxPixels: params.maxPixels,
     minTextChars: params.minTextChars,
+    ...(params.password ? { password: params.password } : {}),
     ...(params.pageNumbers ? { pageNumbers: params.pageNumbers } : {}),
     ...(params.config ? { config: params.config } : {}),
     ...(params.onImageExtractionError
diff --git a/src/plugins/document-extractor-types.ts b/src/plugins/document-extractor-types.ts
@@ -10,6 +10,7 @@ export type DocumentExtractionRequest = {
   maxPages: number;
   maxPixels: number;
   minTextChars: number;
+  password?: string;
   pageNumbers?: number[];
   onImageExtractionError?: (error: unknown) => void;
 };
