Merge pull request #217 from bcgov/develop

Develop

Author: alex-struk

apps/backend-services/src/document/document.service.spec.ts

@@ -9,7 +9,10 @@ import {
 import { UploadNormalizationLimiter } from "../upload/upload-normalization-limiter";
 import { DocumentService } from "./document.service";
 import { DocumentDbService } from "./document-db.service";
-import { PdfNormalizationService } from "./pdf-normalization.service";
+import {
+  PdfNormalizationError,
+  PdfNormalizationService,
+} from "./pdf-normalization.service";
 
 describe("DocumentService", () => {
   let service: DocumentService;
@@ -235,6 +238,72 @@ describe("DocumentService", () => {
       expect(documentDbService.createDocument).toHaveBeenCalled();
     });
 
+    it("returns conversion_failed with the specific code/reason for a password-protected PDF", async () => {
+      const pdfBytes = Buffer.from("%PDF-1.4\n%\xe2\xe3\xcf\xd3\n");
+      const base64 = pdfBytes.toString("base64");
+      pdfNormalization.normalizeToPdf.mockRejectedValue(
+        new PdfNormalizationError(
+          "The PDF is password protected and cannot be processed. Upload an unlocked copy.",
+          "password_protected",
+        ),
+      );
+      (documentDbService.createDocument as jest.Mock).mockImplementation(
+        async (doc: { id: string; status: string }) => ({
+          ...doc,
+          created_at: new Date(),
+          updated_at: new Date(),
+        }),
+      );
+
+      const result = await service.uploadDocument(
+        "Test",
+        base64,
+        "pdf",
+        "encrypted.pdf",
+        "test-model-id",
+        "group-1",
+        {},
+      );
+
+      expect(result.kind).toBe("conversion_failed");
+      if (result.kind !== "conversion_failed") throw new Error("unreachable");
+      expect(result.code).toBe("password_protected");
+      expect(result.reason).toMatch(/password protected/i);
+      expect(result.document.status).toBe(DocumentStatus.conversion_failed);
+      expect(result.document.normalized_file_path).toBeNull();
+    });
+
+    it("returns generic conversion_failed for an unexpected normalization error", async () => {
+      const pdfBytes = Buffer.from("%PDF-1.4\n%\xe2\xe3\xcf\xd3\n");
+      const base64 = pdfBytes.toString("base64");
+      pdfNormalization.normalizeToPdf.mockRejectedValue(
+        new Error("some internal boom"),
+      );
+      (documentDbService.createDocument as jest.Mock).mockImplementation(
+        async (doc: { id: string; status: string }) => ({
+          ...doc,
+          created_at: new Date(),
+          updated_at: new Date(),
+        }),
+      );
+
+      const result = await service.uploadDocument(
+        "Test",
+        base64,
+        "pdf",
+        "file.pdf",
+        "test-model-id",
+        "group-1",
+        {},
+      );
+
+      expect(result.kind).toBe("conversion_failed");
+      if (result.kind !== "conversion_failed") throw new Error("unreachable");
+      // Internal error details are not leaked; falls back to the generic shape.
+      expect(result.code).toBe("conversion_failed");
+      expect(result.reason).toBe("Document could not be converted to PDF");
+    });
+
     it("should throw on invalid base64", async () => {
       await expect(
         service.uploadDocument(

apps/backend-services/src/document/document.service.ts

@@ -47,7 +47,14 @@ export interface UploadedDocument {
 
 export type UploadDocumentResult =
   | { kind: "success"; document: UploadedDocument }
-  | { kind: "conversion_failed"; document: UploadedDocument };
+  | {
+      kind: "conversion_failed";
+      document: UploadedDocument;
+      /** Machine-readable failure reason, e.g. `password_protected`. */
+      code: string;
+      /** Human-readable reason surfaced to the upload caller. */
+      reason: string;
+    };
 
 @Injectable()
 export class DocumentService {
@@ -189,7 +196,18 @@ export class DocumentService {
         if (e instanceof BadRequestException) {
           throw e;
         }
-        if (!(e instanceof PdfNormalizationError)) {
+
+        // Surface the specific reason only for our controlled normalization
+        // errors. Unexpected errors fall back to the generic message/code so
+        // internal details are never leaked to the caller.
+        let code = "conversion_failed";
+        let reason = "Document could not be converted to PDF";
+        if (e instanceof PdfNormalizationError) {
+          reason = e.message;
+          if (e.code) {
+            code = e.code;
+          }
+        } else {
           this.logger.error(
             `Unexpected normalization error: ${e instanceof Error ? e.message : String(e)}`,
           );
@@ -224,6 +242,8 @@ export class DocumentService {
         return {
           kind: "conversion_failed",
           document: this.toUploadedDocument(saved),
+          code,
+          reason,
         };
       }
 

apps/backend-services/src/document/dto/reprocess-document-response.dto.ts

@@ -0,0 +1,21 @@
+import { DocumentStatus } from "@generated/client";
+import { ApiProperty } from "@nestjs/swagger";
+
+/** Response body for a successful document re-run (202 Accepted). */
+export class ReprocessDocumentResponseDto {
+  @ApiProperty({ example: true })
+  success!: boolean;
+
+  @ApiProperty({
+    description: "Temporal workflow execution ID of the new run.",
+    example: "graph-65fafe87-9fa7-46e6-9f1e-ba2ef326e3be",
+  })
+  workflowExecutionId!: string;
+
+  @ApiProperty({
+    enum: DocumentStatus,
+    description: "Document status after the re-run was started.",
+    example: DocumentStatus.ongoing_ocr,
+  })
+  status!: DocumentStatus;
+}

apps/backend-services/src/document/pdf-normalization.service.spec.ts

@@ -190,6 +190,57 @@ describe("PdfNormalizationService", () => {
     });
   });
 
+  describe("normalizeToPdf – password-protected PDFs", () => {
+    function mockNeedsPassword(needsPassword: boolean): void {
+      jest.mocked(loadMupdf).mockResolvedValue({
+        Document: {
+          openDocument: jest.fn(() => ({
+            needsPassword: () => needsPassword,
+          })),
+        },
+      } as unknown as Awaited<ReturnType<typeof loadMupdf>>);
+    }
+
+    afterEach(() => {
+      jest.mocked(loadMupdf).mockReset();
+    });
+
+    it("rejects a password-protected PDF as conversion failure (not OCR)", async () => {
+      const buf = await minimalValidPdfBuffer();
+      mockNeedsPassword(true);
+
+      await expect(service.normalizeToPdf(buf, "pdf")).rejects.toThrow(
+        PdfNormalizationError,
+      );
+    });
+
+    it("includes a clear password-protected message", async () => {
+      const buf = await minimalValidPdfBuffer();
+      mockNeedsPassword(true);
+
+      await expect(service.normalizeToPdf(buf, "pdf")).rejects.toThrow(
+        /password protected/i,
+      );
+    });
+
+    it("tags the error with a `password_protected` code", async () => {
+      const buf = await minimalValidPdfBuffer();
+      mockNeedsPassword(true);
+
+      const error = await service.normalizeToPdf(buf, "pdf").catch((e) => e);
+      expect(error).toBeInstanceOf(PdfNormalizationError);
+      expect((error as PdfNormalizationError).code).toBe("password_protected");
+    });
+
+    it("allows a PDF that does not require a password", async () => {
+      const buf = await minimalValidPdfBuffer();
+      mockNeedsPassword(false);
+
+      const out = await service.normalizeToPdf(buf, "pdf");
+      expect(out.equals(buf)).toBe(true);
+    });
+  });
+
   describe("normalizeToPdf – PDF rotation baking", () => {
     async function pdfWithRotation(angle: number): Promise<Buffer> {
       const doc = await PDFDocument.create();

apps/backend-services/src/document/pdf-normalization.service.ts

@@ -8,9 +8,17 @@ import sharp = require("sharp");
 
 /** Thrown when a valid input could not be converted to PDF (distinct from invalid/corrupt upload). */
 export class PdfNormalizationError extends Error {
-  constructor(message: string) {
+  /**
+   * Optional machine-readable reason surfaced to the upload caller (e.g.
+   * `password_protected`). Defaults to undefined for generic conversion
+   * failures, which the API reports as `conversion_failed`.
+   */
+  readonly code?: string;
+
+  constructor(message: string, code?: string) {
     super(message);
     this.name = "PdfNormalizationError";
+    this.code = code;
   }
 }
 
@@ -233,7 +241,48 @@ export class PdfNormalizationService {
    * angle source is Tesseract OSD detection rather than the PDF /Rotate flag.
    * Keep both sites in sync when changing the math.
    */
+  /**
+   * Rejects PDFs that require a password to open.
+   *
+   * The page-rotation load below uses `ignoreEncryption: true`, which silently
+   * lets password-protected PDFs through normalization; Azure Document
+   * Intelligence then rejects them with `400 UnsupportedContent` ("File may be
+   * password protected"), stranding the document mid-pipeline. mupdf's
+   * `needsPassword()` is the precise gate: it is true only for open-password
+   * encryption, so permission-only encrypted PDFs (which OCR reads fine) are
+   * deliberately allowed through. A throw here surfaces as `conversion_failed`,
+   * keeping the document out of OCR entirely.
+   */
+  private async assertPdfNotPasswordProtected(
+    fileBuffer: Buffer,
+  ): Promise<void> {
+    let requiresPassword: boolean;
+    try {
+      const mupdf = await loadMupdf();
+      const doc = mupdf.Document.openDocument(
+        new Uint8Array(fileBuffer),
+        "application/pdf",
+      );
+      requiresPassword = doc.needsPassword();
+    } catch (e) {
+      // Not openable as a PDF for the probe — let the pdf-lib load below raise
+      // the canonical "not a valid PDF or is corrupted" error instead.
+      this.logger.debug("Password probe could not open PDF", {
+        error: e instanceof Error ? e.message : String(e),
+      });
+      return;
+    }
+    if (requiresPassword) {
+      throw new PdfNormalizationError(
+        "The PDF is password protected and cannot be processed. Upload an unlocked copy.",
+        "password_protected",
+      );
+    }
+  }
+
   private async normalizePdfPageRotations(fileBuffer: Buffer): Promise<Buffer> {
+    await this.assertPdfNotPasswordProtected(fileBuffer);
+
     let srcDoc: PDFDocument;
     try {
       srcDoc = await PDFDocument.load(fileBuffer, { ignoreEncryption: true });

apps/backend-services/src/ocr/ocr.controller.spec.ts

@@ -1,9 +1,12 @@
+import { ForbiddenException, NotFoundException } from "@nestjs/common";
 import { ConfigService } from "@nestjs/config";
 import { Test, TestingModule } from "@nestjs/testing";
 import { Request } from "express";
+import { DocumentService } from "@/document/document.service";
 import { GroupRole } from "@/generated";
 import { TrainingService } from "@/training/training.service";
 import { OcrController } from "./ocr.controller";
+import { OcrService } from "./ocr.service";
 
 /**
  * Builds a request carrying an API-key-style resolved identity scoped to a
@@ -25,6 +28,12 @@ describe("OcrController", () => {
   const mockTrainingService = {
     findAllTrainedModelIds: jest.fn().mockResolvedValue([]),
   };
+  const mockDocumentService = {
+    findDocument: jest.fn(),
+  };
+  const mockOcrService = {
+    reprocessDocument: jest.fn(),
+  };
 
   beforeEach(async () => {
     jest.clearAllMocks();
@@ -46,6 +55,8 @@ describe("OcrController", () => {
           provide: TrainingService,
           useValue: mockTrainingService,
         },
+        { provide: DocumentService, useValue: mockDocumentService },
+        { provide: OcrService, useValue: mockOcrService },
       ],
     }).compile();
 
@@ -101,6 +112,46 @@ describe("OcrController", () => {
     });
   });
 
+  describe("reprocessDocument", () => {
+    const doc = { id: "doc-1", group_id: "group-1" };
+
+    it("throws NotFoundException when the document is missing", async () => {
+      mockDocumentService.findDocument.mockResolvedValue(null);
+      await expect(
+        controller.reprocessDocument("doc-1", buildReq()),
+      ).rejects.toThrow(NotFoundException);
+      expect(mockOcrService.reprocessDocument).not.toHaveBeenCalled();
+    });
+
+    it("throws ForbiddenException when the caller is not a group member", async () => {
+      mockDocumentService.findDocument.mockResolvedValue({
+        ...doc,
+        group_id: "other-group",
+      });
+      await expect(
+        controller.reprocessDocument("doc-1", buildReq("group-1")),
+      ).rejects.toThrow(ForbiddenException);
+      expect(mockOcrService.reprocessDocument).not.toHaveBeenCalled();
+    });
+
+    it("returns the 202 payload and delegates to OcrService on success", async () => {
+      mockDocumentService.findDocument.mockResolvedValue(doc);
+      mockOcrService.reprocessDocument.mockResolvedValue({
+        workflowExecutionId: "graph-doc-1",
+        status: "ongoing_ocr",
+      });
+
+      const result = await controller.reprocessDocument("doc-1", buildReq());
+
+      expect(mockOcrService.reprocessDocument).toHaveBeenCalledWith(doc);
+      expect(result).toEqual({
+        success: true,
+        workflowExecutionId: "graph-doc-1",
+        status: "ongoing_ocr",
+      });
+    });
+  });
+
   describe("getModels with empty config", () => {
     it("should return default model when config is empty", async () => {
       const module: TestingModule = await Test.createTestingModule({
@@ -116,6 +167,8 @@ describe("OcrController", () => {
             provide: TrainingService,
             useValue: mockTrainingService,
           },
+          { provide: DocumentService, useValue: mockDocumentService },
+          { provide: OcrService, useValue: mockOcrService },
         ],
       }).compile();