Decrypt protected PDFs using qpdf and upload new SS-5 form (#691)

Author: kydecker

pdf-manager/lib/handlers.ts

@@ -1,6 +1,5 @@
 import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
-import { PDF } from "@libpdf/core";
 import type { Context } from "hono";
 import { findPdfById, listAllPdfs } from "./catalog";
 import {
@@ -9,7 +8,12 @@ import {
   writeDefinitionFiles,
 } from "./define";
 import { loadJurisdictions } from "./fields";
-import { applyRenames, extractFields, extractFieldsFromBytes } from "./pdf";
+import {
+  applyRenames,
+  extractFields,
+  extractFieldsFromBytes,
+  loadPdf,
+} from "./pdf";
 import { loadExclusions, processPdf } from "./schema";
 import { suggestName } from "./suggest";
 
@@ -108,7 +112,7 @@ export async function handleAddPdf(c: Context) {
   }
 
   const rawBytes = Buffer.from(pdfBase64, "base64");
-  const pdfDoc = await PDF.load(rawBytes);
+  const pdfDoc = await loadPdf(rawBytes);
   const cleanedBytes = await pdfDoc.save();
 
   const pdfFields = await extractFieldsFromBytes(cleanedBytes);
@@ -198,7 +202,7 @@ export async function handleReplacePdf(c: Context) {
   let fieldNames: string[];
   try {
     const newBytes = Buffer.from(pdfBase64, "base64");
-    const pdfDoc = await PDF.load(newBytes);
+    const pdfDoc = await loadPdf(newBytes);
     writeFileSync(found.pdfPath, await pdfDoc.save());
 
     if (renames.length > 0) await applyRenames(found.pdfPath, renames);
@@ -216,12 +220,12 @@ export async function handleReplacePdf(c: Context) {
       exclude: deletes,
       keep: keepNames,
     }));
-    formatFiles([schemaPath]);
   } catch (err) {
     writeFileSync(found.pdfPath, oldBytes);
     writeFileSync(schemaPath, oldSchemaContent);
     throw err;
   }
+  formatFiles([schemaPath]);
 
   const before = new Set(activeFields);
   const fieldSet = new Set(fieldNames);

pdf-manager/lib/pdf.ts

@@ -1,4 +1,7 @@
-import { readFileSync, writeFileSync } from "node:fs";
+import { spawnSync } from "node:child_process";
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
 import type { FieldType, FormField, PDFPage } from "@libpdf/core";
 import { PDF, PdfArray, PdfDict, PdfName, PdfString } from "@libpdf/core";
 
@@ -62,16 +65,63 @@ export async function extractFields(pdfPath: string): Promise<PdfFieldInfo[]> {
   return extractFieldsFromBytes(readFileSync(pdfPath));
 }
 
+export async function loadPdf(bytes: Uint8Array | Buffer): Promise<PDF> {
+  const doc = await PDF.load(bytes);
+  if (!doc.isEncrypted) return doc;
+  return PDF.load(decryptWithQpdf(bytes));
+}
+
 /** Same as extractFields but accepts raw bytes instead of a path. */
 export async function extractFieldsFromBytes(
   bytes: Uint8Array | Buffer,
 ): Promise<PdfFieldInfo[]> {
-  const doc = await PDF.load(bytes);
+  const doc = await loadPdf(bytes);
   const form = doc.getForm();
   const sorted = fieldReadingOrder(form?.getFields() ?? [], doc.getPages());
   return sorted.map((f) => ({ name: f.name, type: f.type }));
 }
 
+/**
+ * Temporary workaround for https://github.com/LibPDF-js/core/issues/82.
+ *
+ * When a PDF is encrypted with an empty user password but an unknown owner
+ * password, libpdf authenticates successfully (isAuthenticated: true) but
+ * removeProtection() throws PermissionDeniedError. Calling save() without
+ * removing protection regenerates the /ID trailer entry, invalidating the AES
+ * key derivation — the saved file is unreadable. qpdf derives the correct file
+ * key from the empty user password and strips encryption without needing the
+ * owner password. Remove this function and inline PDF.load() in loadPdf() once
+ * libpdf preserves the original /ID on save().
+ */
+function decryptWithQpdf(bytes: Uint8Array | Buffer): Buffer {
+  const tmpDir = mkdtempSync(join(tmpdir(), "namesake-pdf-"));
+  try {
+    const inPath = join(tmpDir, "input.pdf");
+    const outPath = join(tmpDir, "output.pdf");
+    writeFileSync(inPath, bytes);
+    const result = spawnSync("qpdf", ["--decrypt", inPath, outPath], {
+      timeout: 60_000,
+    });
+    if (result.error) {
+      const isNotFound =
+        (result.error as NodeJS.ErrnoException).code === "ENOENT";
+      throw new Error(
+        isNotFound
+          ? "qpdf is required to process encrypted PDFs. Install it with: brew install qpdf"
+          : `qpdf failed: ${result.error.message}`,
+      );
+    }
+    if (result.status !== 0) {
+      throw new Error(
+        "PDF is password-protected. Please provide an unprotected version.",
+      );
+    }
+    return readFileSync(outPath);
+  } finally {
+    rmSync(tmpDir, { recursive: true, force: true });
+  }
+}
+
 /**
  * Converts all dropdown fields to plain text fields in the PDF on disk.
  * This lets fillPdf write any value without needing to match the PDF's fixed
@@ -81,7 +131,7 @@ export async function convertDropdownsToTextFields(
   pdfPath: string,
 ): Promise<void> {
   const bytes = readFileSync(pdfPath);
-  const doc = await PDF.load(bytes);
+  const doc = await loadPdf(bytes);
   const form = doc.getForm();
   let changed = false;
   for (const field of form?.getFields() ?? []) {
@@ -105,7 +155,7 @@ export async function normalizeRadioOptionNames(
   pdfPath: string,
 ): Promise<void> {
   const bytes = readFileSync(pdfPath);
-  const doc = await PDF.load(bytes);
+  const doc = await loadPdf(bytes);
   const form = doc.getForm();
   let changed = false;
 
@@ -176,7 +226,7 @@ export async function applyRenames(
   renames: Rename[],
 ): Promise<void> {
   const bytes = readFileSync(pdfPath);
-  const doc = await PDF.load(bytes);
+  const doc = await loadPdf(bytes);
   const form = doc.getForm();
   const acroForm = form?.acroForm();
   for (const { from, to } of renames) {

pnpm-lock.yaml

@@ -64,6 +64,7 @@
     "fathom-client": "^3.7.2",
     "idb": "^8.0.3",
     "language-name-map": "^0.3.0",
+    "libphonenumber-js": "^1.13.8",
     "react": "^19.2.7",
     "react-aria-components": "^1.19.0",
     "react-dom": "^19.2.7",

web/package.json

@@ -161,6 +161,10 @@ describe("getYesNoStringFromBoolean", () => {
     );
   });
 
+  it("returns 'dontKnow' if the value is 'dontKnow'", () => {
+    expect(getYesNoStringFromBoolean("dontKnow")).toBe("dontKnow");
+  });
+
   it("returns null if the value is undefined", () => {
     expect(getYesNoStringFromBoolean(undefined as any)).toBeNull();
   });
@@ -185,6 +189,10 @@ describe("getBooleanValueFromYesNoString", () => {
     );
   });
 
+  it("returns 'dontKnow' if the value is 'dontKnow'", () => {
+    expect(getBooleanValueFromYesNoString("dontKnow")).toBe("dontKnow");
+  });
+
   it("returns false for other values", () => {
     expect(getBooleanValueFromYesNoString("")).toBe(false);
     expect(getBooleanValueFromYesNoString("garbage")).toBe(false);

web/src/components/forms/YesNoField/YesNoField.test.tsx

@@ -1,5 +1,9 @@
 import { Controller, useFormContext } from "react-hook-form";
-import { type FieldName, PREFER_NOT_TO_ANSWER } from "#constants/fields";
+import {
+  DONT_KNOW,
+  type FieldName,
+  PREFER_NOT_TO_ANSWER,
+} from "#constants/fields";
 import { smartquotes } from "#lib/utils/smartquotes";
 import {
   Radio,
@@ -8,27 +12,19 @@ import {
 } from "../../common/RadioGroup";
 import "./YesNoField.css";
 
-type YesNoValue = boolean | typeof PREFER_NOT_TO_ANSWER;
+type YesNoValue = boolean | typeof PREFER_NOT_TO_ANSWER | typeof DONT_KNOW;
 
-/**
- * Converts a boolean value to a string value.
- * @param value - The boolean value to convert.
- * @returns "yes" if the value is true, "no" if the value is false, "preferNotToAnswer" if the value is null.
- */
 export const getYesNoStringFromBoolean = (value: YesNoValue) => {
   if (value === undefined || value === null) return null;
   if (value === PREFER_NOT_TO_ANSWER) return PREFER_NOT_TO_ANSWER;
+  if (value === DONT_KNOW) return DONT_KNOW;
   if (value) return "yes";
   return "no";
 };
 
-/**
- * Converts a string value to a boolean value.
- * @param value - The string value to convert.
- * @returns true if the value is "yes", false if the value is "no", null if the value is "preferNotToAnswer".
- */
 export const getBooleanValueFromYesNoString = (value: string): YesNoValue => {
   if (value === PREFER_NOT_TO_ANSWER) return PREFER_NOT_TO_ANSWER;
+  if (value === DONT_KNOW) return DONT_KNOW;
   return value === "yes";
 };
 
@@ -40,6 +36,7 @@ export interface YesNoFieldProps extends RadioGroupProps {
   yesLabel?: string;
   noLabel?: string;
   includePreferNotToAnswer?: boolean;
+  includeDontKnow?: boolean;
 }
 
 export function YesNoField({
@@ -51,6 +48,7 @@ export function YesNoField({
   children,
   defaultValue,
   includePreferNotToAnswer,
+  includeDontKnow,
 }: YesNoFieldProps) {
   const { control, setValue } = useFormContext();
 
@@ -77,6 +75,7 @@ export function YesNoField({
             {includePreferNotToAnswer && (
               <Radio value={PREFER_NOT_TO_ANSWER}>Prefer not to answer</Radio>
             )}
+            {includeDontKnow && <Radio value={DONT_KNOW}>I don’t know</Radio>}
           </RadioGroup>
         )}
       />

web/src/components/forms/YesNoField/YesNoField.tsx

@@ -702,7 +702,7 @@ export type FieldType<K extends FieldName> = K extends any
           (typeof FIELD_DEFS)[number],
           { name: K }
         >["type"] extends "boolean"
-      ? boolean
+      ? boolean | typeof PREFER_NOT_TO_ANSWER | typeof DONT_KNOW
       : Extract<
             (typeof FIELD_DEFS)[number],
             { name: K }
@@ -718,3 +718,4 @@ export type FormData = {
 export const COMMON_PRONOUNS = ["they/them", "she/her", "he/him"];
 
 export const PREFER_NOT_TO_ANSWER = "preferNotToAnswer";
+export const DONT_KNOW = "dontKnow";

web/src/constants/fields.ts

@@ -36,6 +36,7 @@ export const previousSocialSecurityCardStep = defineStep({
           labelHidden
           yesLabel="Yes, I have a previous Social Security card or have applied for one"
           noLabel="No, I have never filed for or received a Social Security card before"
+          includeDontKnow
         />
         <FormSubsection
           title="What is the name shown on your most recent Social Security card?"

web/src/content/forms/social-security/steps/PreviousSocialSecurityCardStep.tsx

@@ -1,4 +1,5 @@
 import { describe, expect, it } from "vitest";
+import { DONT_KNOW } from "#constants/fields";
 import { expectPdfFieldsMatch } from "#lib/pdfs/expectPdfFieldsMatch";
 import { getPdfForm } from "#lib/pdfs/getPdfForm";
 import ss5Application from ".";
@@ -52,7 +53,7 @@ describe("SS-5 Application for Social Security Card", () => {
     previousSocialSecurityCardLastName: "Michaels, Jr.",
 
     // Field 15: Phone number
-    phoneNumber: "555-555-5555",
+    phoneNumber: "212-867-5309",
 
     // Field 16: Address
     mailingStreetAddress: "123 Main St",
@@ -69,6 +70,31 @@ describe("SS-5 Application for Social Security Card", () => {
     await expectPdfFieldsMatch(ss5Application, testData);
   });
 
+  it("splits phone number into area code and local number", async () => {
+    const form = await getPdfForm({ pdf: ss5Application, userData: testData });
+    expect(form.getTextField("areaCode")?.getValue()).toBe("212");
+    expect(form.getTextField("phoneNumber")?.getValue()).toBe("867-5309");
+  });
+
+  it("checks previousSocialSecurityCardUnknown when hasPreviousSocialSecurityCard is unknown", async () => {
+    const form = await getPdfForm({
+      pdf: ss5Application,
+      userData: {
+        ...testData,
+        hasPreviousSocialSecurityCard: DONT_KNOW,
+      },
+    });
+    expect(
+      form.getCheckbox("previousSocialSecurityCardUnknown")?.isChecked(),
+    ).toBe(true);
+    expect(form.getCheckbox("hasPreviousSocialSecurityCard")?.isChecked()).toBe(
+      false,
+    );
+    expect(
+      form.getCheckbox("hasNoPreviousSocialSecurityCard")?.isChecked(),
+    ).toBe(false);
+  });
+
   it("derives birthplaceState from country code when outside US", async () => {
     const dataWithForeignBirthplace = {
       ...testData,

web/src/content/pdfs/federal/ss5-application-for-social-security-card/index.test.ts

@@ -1,6 +1,8 @@
+import { DONT_KNOW } from "#constants/fields";
 import { definePdf } from "#lib/pdfs/definePdf";
 import { formatBirthplaceCountryOrState } from "#lib/utils/formatBirthplaceCountryOrState";
 import { formatDateMMDDYYYY } from "#lib/utils/formatDateMMDDYYYY";
+import { splitPhoneNumber } from "#lib/utils/splitPhoneNumber";
 import type { PdfFieldName } from "./schema";
 import pdf from "./ss5-application-for-social-security-card.pdf";
 
@@ -50,6 +52,8 @@ export default definePdf<PdfFieldName>({
     hasPreviousSocialSecurityCard: data.hasPreviousSocialSecurityCard === true,
     hasNoPreviousSocialSecurityCard:
       data.hasPreviousSocialSecurityCard === false,
+    previousSocialSecurityCardUnknown:
+      data.hasPreviousSocialSecurityCard === DONT_KNOW,
     previousSocialSecurityCardFirstName:
       data.previousSocialSecurityCardFirstName,
     previousSocialSecurityCardMiddleName:
@@ -60,7 +64,8 @@ export default definePdf<PdfFieldName>({
       day: "2-digit",
       year: "numeric",
     }),
-    phoneNumber: data.phoneNumber,
+    areaCode: splitPhoneNumber(data.phoneNumber).areaCode,
+    phoneNumber: splitPhoneNumber(data.phoneNumber).localNumber,
     mailingStreetAddress: data.mailingStreetAddress,
     mailingCity: data.mailingCity,
     mailingState: data.mailingState,