pdf-visual-compare 3.4.0 → 4.0.0

package/out/internal/diffOutputGuards.js

@@ -0,0 +1,176 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateDiffsOutputFolder = validateDiffsOutputFolder;
+exports.ensureDiffOutputDirectory = ensureDiffOutputDirectory;
+exports.assertDiffOutputPathUsesRealFilesystemEntries = assertDiffOutputPathUsesRealFilesystemEntries;
+exports.createSecureDiffOutputTempfile = createSecureDiffOutputTempfile;
+exports.publishDiffOutputTempfile = publishDiffOutputTempfile;
+exports.discardDiffOutputLeaf = discardDiffOutputLeaf;
+exports.assertCanonicalDiffOutputPath = assertCanonicalDiffOutputPath;
+const node_fs_1 = require("node:fs");
+const node_crypto_1 = require("node:crypto");
+const node_path_1 = require("node:path");
+const ComparePdfConfigurationError_js_1 = require("../errors/ComparePdfConfigurationError.js");
+const const_js_1 = require("../const.js");
+const securePath_js_1 = require("./securePath.js");
+function validateDiffsOutputFolder(diffsOutputFolder) {
+    const outputFolder = diffsOutputFolder === undefined ? (0, const_js_1.getDefaultDiffsFolder)() : diffsOutputFolder;
+    if (typeof outputFolder !== 'string' || outputFolder.trim() === '') {
+        throw new ComparePdfConfigurationError_js_1.ComparePdfConfigurationError('diffsOutputFolder must be a non-empty string.');
+    }
+    const resolvedOutputFolder = (0, node_path_1.resolve)(outputFolder);
+    if ((0, node_fs_1.existsSync)(resolvedOutputFolder) && !(0, node_fs_1.statSync)(resolvedOutputFolder).isDirectory()) {
+        throw new ComparePdfConfigurationError_js_1.ComparePdfConfigurationError(`diffsOutputFolder must point to a directory when it already exists: ${outputFolder}`);
+    }
+    (0, securePath_js_1.assertPathAndAncestorsAreNotSymbolicLinks)(resolvedOutputFolder, `Diff output path must stay within diffsOutputFolder: ${(0, node_path_1.resolve)(outputFolder)}`);
+    return resolvedOutputFolder;
+}
+function ensureDiffOutputDirectory(outputPath, diffsOutputFolder) {
+    try {
+        (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(outputPath), { recursive: true });
+    }
+    catch (cause) {
+        throw new ComparePdfConfigurationError_js_1.ComparePdfConfigurationError(`diffsOutputFolder must point to a writable directory: ${diffsOutputFolder}`, { cause });
+    }
+}
+function assertDiffOutputPathUsesRealFilesystemEntries(diffFilePath, diffsOutputFolder) {
+    const resolvedDiffsOutputFolder = (0, node_path_1.resolve)(diffsOutputFolder);
+    const diffsOutputFolderErrorMessage = `Diff output path must stay within diffsOutputFolder: ${(0, node_path_1.resolve)(diffsOutputFolder)}`;
+    if ((0, securePath_js_1.pathExistsWithoutFollowingSymlinks)(resolvedDiffsOutputFolder)) {
+        (0, securePath_js_1.assertPathIsNotSymbolicLink)(resolvedDiffsOutputFolder, diffsOutputFolderErrorMessage);
+    }
+    const relativeDiffPath = (0, node_path_1.relative)(resolvedDiffsOutputFolder, (0, node_path_1.resolve)(diffFilePath));
+    if (relativeDiffPath === '' || (0, node_path_1.isAbsolute)(relativeDiffPath) || relativeDiffPath.startsWith('..')) {
+        return;
+    }
+    let currentPath = resolvedDiffsOutputFolder;
+    for (const segment of relativeDiffPath.split(node_path_1.sep)) {
+        currentPath = (0, node_path_1.resolve)(currentPath, segment);
+        if (!(0, securePath_js_1.pathExistsWithoutFollowingSymlinks)(currentPath)) {
+            return;
+        }
+        (0, securePath_js_1.assertPathIsNotSymbolicLink)(currentPath, diffsOutputFolderErrorMessage);
+    }
+}
+/**
+ * Atomically creates a fresh, randomly-named tempfile in the same directory as the diff leaf
+ * and returns its path. The third-party comparator is then directed at this tempfile, and the
+ * result is later promoted into `diffFilePath` via {@link publishDiffOutputTempfile}.
+ *
+ * This two-step "stage then rename" pattern is materially stronger than writing directly to
+ * `diffFilePath`:
+ * - The tempfile name carries an unpredictable random suffix, so an attacker with write
+ *   access in `diffsOutputFolder` cannot pre-plant a symlink at the future tempfile path.
+ * - The tempfile is opened with `O_CREAT | O_EXCL | O_NOFOLLOW`, so any racing attempt to
+ *   pre-create a regular file or symlink at the same path during the open is rejected
+ *   (CWE-61 / CWE-367).
+ * - The eventual atomic `renameSync` (see {@link publishDiffOutputTempfile}) replaces any
+ *   pre-existing entry at `diffFilePath` — including a symlink planted there during the
+ *   write window — without ever following the destination's symlink.
+ */
+function createSecureDiffOutputTempfile(diffFilePath, diffsOutputFolder) {
+    const tempfilePath = buildSecureTempfilePath(diffFilePath);
+    let fileDescriptor;
+    try {
+        fileDescriptor = (0, node_fs_1.openSync)(tempfilePath, node_fs_1.constants.O_WRONLY | node_fs_1.constants.O_CREAT | node_fs_1.constants.O_EXCL | node_fs_1.constants.O_NOFOLLOW, 0o600);
+    }
+    catch (cause) {
+        if (isSymbolicLinkAtLeafError(cause) || isExistingLeafError(cause)) {
+            throw new ComparePdfConfigurationError_js_1.ComparePdfConfigurationError(`Diff output path must stay within diffsOutputFolder: ${(0, node_path_1.resolve)(diffsOutputFolder)}`, { cause });
+        }
+        throw new ComparePdfConfigurationError_js_1.ComparePdfConfigurationError(`diffsOutputFolder must point to a writable directory: ${diffsOutputFolder}`, { cause });
+    }
+    finally {
+        if (fileDescriptor !== undefined) {
+            (0, node_fs_1.closeSync)(fileDescriptor);
+        }
+    }
+    return tempfilePath;
+}
+function buildSecureTempfilePath(diffFilePath) {
+    const parentDir = (0, node_path_1.dirname)(diffFilePath);
+    const leafName = (0, node_path_1.basename)(diffFilePath);
+    // 128 bits of randomness make pre-planting the tempfile path infeasible even for an
+    // attacker who can race writes inside the diffs folder.
+    const randomSuffix = (0, node_crypto_1.randomBytes)(16).toString('hex');
+    return (0, node_path_1.resolve)(parentDir, `.${leafName}.${randomSuffix}.tmp`);
+}
+/**
+ * Promotes the staged tempfile to `diffFilePath` via atomic `renameSync`. This is the
+ * core anti-TOCTOU primitive: `rename()` replaces any pre-existing file or symlink at
+ * the destination as a single directory-entry operation without ever following the
+ * destination. A symlink planted at `diffFilePath` during the write window is therefore
+ * harmlessly overwritten — the attacker's chosen target is never opened by this library.
+ *
+ * Throws `ComparePdfConfigurationError` when:
+ * - the tempfile is no longer a regular file (symlink swap during the comparator's write
+ *   — bytes may have leaked through the swapped symlink to an attacker-chosen target);
+ * - a diff was expected but the tempfile is missing or zero bytes;
+ * - the tempfile cannot be inspected, or rename fails for reasons other than absence.
+ */
+function publishDiffOutputTempfile(tempfilePath, diffFilePath, diffsOutputFolder, options) {
+    let tempStats;
+    try {
+        tempStats = (0, node_fs_1.lstatSync)(tempfilePath);
+    }
+    catch (cause) {
+        if (isMissingLeafError(cause)) {
+            if (options.expectDiffWritten) {
+                throw new ComparePdfConfigurationError_js_1.ComparePdfConfigurationError(`Diff output was expected but is missing: ${(0, node_path_1.resolve)(diffFilePath)}`, { cause });
+            }
+            // Comparator skipped writing AND there is no tempfile — also drop any stale
+            // leaf at the published path so the on-disk shape matches pre-fix behavior.
+            discardDiffOutputLeaf(diffFilePath);
+            return;
+        }
+        throw new ComparePdfConfigurationError_js_1.ComparePdfConfigurationError(`Diff output path must stay within diffsOutputFolder: ${(0, node_path_1.resolve)(diffsOutputFolder)}`, { cause });
+    }
+    if (!tempStats.isFile()) {
+        discardDiffOutputLeaf(tempfilePath);
+        throw new ComparePdfConfigurationError_js_1.ComparePdfConfigurationError(`Diff output tempfile was replaced during the write window: ${(0, node_path_1.resolve)(tempfilePath)}`);
+    }
+    if (tempStats.size === 0) {
+        discardDiffOutputLeaf(tempfilePath);
+        if (options.expectDiffWritten) {
+            throw new ComparePdfConfigurationError_js_1.ComparePdfConfigurationError(`Diff output was expected but is empty: ${(0, node_path_1.resolve)(diffFilePath)}`);
+        }
+        discardDiffOutputLeaf(diffFilePath);
+        return;
+    }
+    try {
+        (0, node_fs_1.renameSync)(tempfilePath, diffFilePath);
+    }
+    catch (cause) {
+        discardDiffOutputLeaf(tempfilePath);
+        throw new ComparePdfConfigurationError_js_1.ComparePdfConfigurationError(`Failed to publish diff output to ${(0, node_path_1.resolve)(diffFilePath)}`, { cause });
+    }
+}
+/**
+ * Best-effort removal of a diff output file. Callers use this to roll back the staged
+ * tempfile when the third-party comparator throws before writing, and to clear stale
+ * leaves at the published path when no diff was produced for matching pages.
+ */
+function discardDiffOutputLeaf(diffFilePath) {
+    try {
+        (0, node_fs_1.unlinkSync)(diffFilePath);
+    }
+    catch {
+        // Best-effort cleanup only.
+    }
+}
+function isSymbolicLinkAtLeafError(cause) {
+    return cause instanceof Error && 'code' in cause && (cause.code === 'ELOOP' || cause.code === 'EMLINK');
+}
+function isExistingLeafError(cause) {
+    return cause instanceof Error && 'code' in cause && cause.code === 'EEXIST';
+}
+function isMissingLeafError(cause) {
+    return cause instanceof Error && 'code' in cause && cause.code === 'ENOENT';
+}
+function assertCanonicalDiffOutputPath(diffFilePath, diffsOutputFolder) {
+    const canonicalDiffsOutputFolder = (0, node_fs_1.realpathSync)(diffsOutputFolder);
+    const canonicalDiffFileParent = (0, node_fs_1.realpathSync)((0, node_path_1.dirname)(diffFilePath));
+    if (!(0, securePath_js_1.isPathWithinRoot)(canonicalDiffFileParent, canonicalDiffsOutputFolder)) {
+        throw new ComparePdfConfigurationError_js_1.ComparePdfConfigurationError(`Diff output path must stay within diffsOutputFolder: ${(0, node_path_1.resolve)(diffsOutputFolder)}`);
+    }
+}

package/out/internal/normalizeComparisonOptions.d.ts

@@ -0,0 +1,2 @@
+import type { NormalizedComparePdfOptions } from './types.js';
+export declare function normalizeComparisonOptions(opts: unknown): NormalizedComparePdfOptions;

package/out/internal/normalizeComparisonOptions.js

@@ -0,0 +1,104 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizeComparisonOptions = normalizeComparisonOptions;
+const comparePngOptions_js_1 = require("./adapters/comparePngOptions.js");
+const pdfRenderOptions_js_1 = require("./adapters/pdfRenderOptions.js");
+const diffOutputGuards_js_1 = require("./diffOutputGuards.js");
+const normalizePdfInput_js_1 = require("./normalizePdfInput.js");
+const renderOutputFolderGuards_js_1 = require("./renderOutputFolderGuards.js");
+const ComparePdfConfigurationError_js_1 = require("../errors/ComparePdfConfigurationError.js");
+const UNSUPPORTED_PDF_RENDER_OPTIONS = [
+    'returnPageContent',
+    'returnMetadataOnly',
+    'processPagesInParallel',
+    'concurrencyLimit',
+];
+function normalizeComparisonOptions(opts) {
+    const compareOptions = validateComparePdfOptions(opts);
+    const allowedInputRoot = (0, normalizePdfInput_js_1.validateAllowedInputRoot)(compareOptions.allowedInputRoot);
+    validatePdfRenderOptions(compareOptions.pdfToPngConvertOptions);
+    const pdfToPngConvertOpts = (0, pdfRenderOptions_js_1.toPdfToPngOptions)(compareOptions.pdfToPngConvertOptions);
+    if (!pdfToPngConvertOpts.viewportScale) {
+        pdfToPngConvertOpts.viewportScale = 2.0;
+    }
+    if (!pdfToPngConvertOpts.outputFileMaskFunc) {
+        pdfToPngConvertOpts.outputFileMaskFunc = (pageNumber) => `comparePdf_${pageNumber}.png`;
+    }
+    pdfToPngConvertOpts.outputFolder = (0, renderOutputFolderGuards_js_1.validateRenderOutputFolder)(pdfToPngConvertOpts.outputFolder);
+    const writeDiffs = compareOptions.writeDiffs ?? false;
+    const diffsOutputFolder = (0, diffOutputGuards_js_1.validateDiffsOutputFolder)(compareOptions.diffsOutputFolder);
+    const compareThreshold = compareOptions.compareThreshold ?? 0;
+    const excludedAreas = validateExcludedAreas(compareOptions.excludedAreas);
+    validateThreshold(compareThreshold, 'Compare Threshold');
+    for (const pageExclusion of excludedAreas) {
+        validatePageNumber(pageExclusion.pageNumber);
+        validateThreshold(pageExclusion.matchingThreshold, 'Matching Threshold');
+        if (pageExclusion.diffFilePath !== undefined) {
+            validateDiffFilePath(pageExclusion.diffFilePath);
+        }
+        if (writeDiffs && pageExclusion.diffFilePath !== undefined) {
+            (0, comparePngOptions_js_1.toComparePngOptions)(pageExclusion, diffsOutputFolder, `comparePdf_${pageExclusion.pageNumber}.png`, true);
+        }
+    }
+    return {
+        allowedInputRoot,
+        compareThreshold,
+        diffsOutputFolder,
+        excludedAreas,
+        pdfToPngConvertOpts,
+        writeDiffs,
+    };
+}
+function validateThreshold(value, thresholdName) {
+    if (value === undefined) {
+        return;
+    }
+    if (!Number.isFinite(value) || !Number.isInteger(value) || value < 0) {
+        throw new ComparePdfConfigurationError_js_1.ComparePdfConfigurationError(`${thresholdName} must be a finite non-negative integer.`);
+    }
+}
+function validatePageNumber(pageNumber) {
+    if (!Number.isFinite(pageNumber) || !Number.isInteger(pageNumber) || pageNumber <= 0) {
+        throw new ComparePdfConfigurationError_js_1.ComparePdfConfigurationError('Page Number must be a finite positive integer.');
+    }
+}
+function validateComparePdfOptions(opts) {
+    if (opts === undefined) {
+        return {};
+    }
+    if (opts === null || typeof opts !== 'object' || Array.isArray(opts)) {
+        throw new ComparePdfConfigurationError_js_1.ComparePdfConfigurationError('Options must be an object.');
+    }
+    return opts;
+}
+function validateExcludedAreas(excludedAreas) {
+    if (excludedAreas === undefined) {
+        return [];
+    }
+    if (!Array.isArray(excludedAreas)) {
+        throw new ComparePdfConfigurationError_js_1.ComparePdfConfigurationError('excludedAreas must be an array.');
+    }
+    for (const pageExclusion of excludedAreas) {
+        if (pageExclusion === null || typeof pageExclusion !== 'object' || Array.isArray(pageExclusion)) {
+            throw new ComparePdfConfigurationError_js_1.ComparePdfConfigurationError('Each excludedAreas entry must be an object.');
+        }
+    }
+    return excludedAreas;
+}
+function validatePdfRenderOptions(pdfRenderOptions) {
+    if (pdfRenderOptions === undefined) {
+        return;
+    }
+    if (pdfRenderOptions === null || typeof pdfRenderOptions !== 'object' || Array.isArray(pdfRenderOptions)) {
+        throw new ComparePdfConfigurationError_js_1.ComparePdfConfigurationError('pdfToPngConvertOptions must be an object.');
+    }
+    const unsupportedOptions = UNSUPPORTED_PDF_RENDER_OPTIONS.filter((optionName) => optionName in pdfRenderOptions);
+    if (unsupportedOptions.length > 0) {
+        throw new ComparePdfConfigurationError_js_1.ComparePdfConfigurationError(`Unsupported pdfToPngConvertOptions properties: ${unsupportedOptions.join(', ')}. comparePdf always renders page content sequentially.`);
+    }
+}
+function validateDiffFilePath(diffFilePath) {
+    if (typeof diffFilePath !== 'string' || diffFilePath.trim() === '') {
+        throw new ComparePdfConfigurationError_js_1.ComparePdfConfigurationError('diffFilePath must be a non-empty string.');
+    }
+}

package/out/internal/normalizePdfInput.d.ts

@@ -0,0 +1,13 @@
+import type { ComparePdfOptions } from '../types/ComparePdfOptions.js';
+import type { PdfInput } from '../types/PdfInput.js';
+import type { AllowedInputRoot } from './types.js';
+/**
+ * Validates the type of the input file.
+ *
+ * Accepts a `Buffer`, `ArrayBuffer`, `SharedArrayBuffer`, or a string path. When
+ * `allowedInputRoot` is configured, string paths must also resolve within that directory.
+ * String paths are resolved and read directly so downstream filesystem errors become the
+ * single source of truth for file access failures. Throws for any other input.
+ */
+export declare function normalizePdfInput(inputFile: unknown, inputLabel: 'actualPdf' | 'expectedPdf', allowedInputRoot?: AllowedInputRoot): PdfInput;
+export declare function validateAllowedInputRoot(allowedInputRoot: ComparePdfOptions['allowedInputRoot']): AllowedInputRoot | undefined;

package/out/internal/normalizePdfInput.js

@@ -0,0 +1,110 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizePdfInput = normalizePdfInput;
+exports.validateAllowedInputRoot = validateAllowedInputRoot;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const ComparePdfConfigurationError_js_1 = require("../errors/ComparePdfConfigurationError.js");
+const ComparePdfInputError_js_1 = require("../errors/ComparePdfInputError.js");
+const securePath_js_1 = require("./securePath.js");
+/**
+ * Validates the type of the input file.
+ *
+ * Accepts a `Buffer`, `ArrayBuffer`, `SharedArrayBuffer`, or a string path. When
+ * `allowedInputRoot` is configured, string paths must also resolve within that directory.
+ * String paths are resolved and read directly so downstream filesystem errors become the
+ * single source of truth for file access failures. Throws for any other input.
+ */
+function normalizePdfInput(inputFile, inputLabel, allowedInputRoot) {
+    if (Buffer.isBuffer(inputFile) || inputFile instanceof ArrayBuffer || inputFile instanceof SharedArrayBuffer) {
+        return inputFile;
+    }
+    if (typeof inputFile === 'string') {
+        const resolvedInputPath = (0, node_path_1.resolve)(inputFile);
+        assertStringPathWithinAllowedInputRoot(resolvedInputPath, inputLabel, allowedInputRoot);
+        let inputFileDescriptor;
+        try {
+            const canonicalInputPath = (0, node_fs_1.realpathSync)(resolvedInputPath);
+            assertStringPathWithinAllowedInputRoot(canonicalInputPath, inputLabel, allowedInputRoot);
+            const canonicalInputStats = (0, node_fs_1.statSync)(canonicalInputPath);
+            if (!canonicalInputStats.isFile()) {
+                throw new ComparePdfInputError_js_1.ComparePdfInputError(`PDF path is not a file: ${inputFile}`);
+            }
+            inputFileDescriptor = (0, node_fs_1.openSync)(canonicalInputPath, openFlagsFor(allowedInputRoot));
+            if (allowedInputRoot) {
+                const openedInputStats = (0, node_fs_1.fstatSync)(inputFileDescriptor);
+                if (openedInputStats.dev !== canonicalInputStats.dev ||
+                    openedInputStats.ino !== canonicalInputStats.ino) {
+                    throw new ComparePdfConfigurationError_js_1.ComparePdfConfigurationError(`${inputLabel} must resolve within allowedInputRoot: ${allowedInputRoot.displayPath}`);
+                }
+            }
+            return (0, node_fs_1.readFileSync)(inputFileDescriptor);
+        }
+        catch (cause) {
+            throw wrapPdfInputReadError(cause, inputFile, inputLabel, allowedInputRoot);
+        }
+        finally {
+            if (inputFileDescriptor !== undefined) {
+                (0, node_fs_1.closeSync)(inputFileDescriptor);
+            }
+        }
+    }
+    throw new ComparePdfInputError_js_1.ComparePdfInputError('Unknown input file type.');
+}
+function validateAllowedInputRoot(allowedInputRoot) {
+    if (allowedInputRoot === undefined) {
+        return undefined;
+    }
+    if (typeof allowedInputRoot !== 'string' || allowedInputRoot.trim().length === 0) {
+        throw new ComparePdfConfigurationError_js_1.ComparePdfConfigurationError('allowedInputRoot must be a non-empty string.');
+    }
+    const resolvedRootPath = (0, node_path_1.resolve)(allowedInputRoot);
+    if (!(0, node_fs_1.existsSync)(resolvedRootPath)) {
+        throw new ComparePdfConfigurationError_js_1.ComparePdfConfigurationError(`allowedInputRoot does not exist: ${allowedInputRoot}`);
+    }
+    const canonicalRootPath = (0, node_fs_1.realpathSync)(resolvedRootPath);
+    if (!(0, node_fs_1.statSync)(canonicalRootPath).isDirectory()) {
+        throw new ComparePdfConfigurationError_js_1.ComparePdfConfigurationError(`allowedInputRoot must point to an existing directory: ${allowedInputRoot}`);
+    }
+    return {
+        displayPath: allowedInputRoot,
+        resolvedPath: resolvedRootPath,
+        canonicalPath: canonicalRootPath,
+    };
+}
+function openFlagsFor(allowedInputRoot) {
+    // When allowedInputRoot is configured, refuse to follow a symlink at the canonical leaf.
+    // This closes a TOCTOU window where an attacker swaps the resolved file with a symlink
+    // between realpathSync and openSync, which would otherwise traverse out of the sandbox.
+    return allowedInputRoot ? node_fs_1.constants.O_RDONLY | node_fs_1.constants.O_NOFOLLOW : node_fs_1.constants.O_RDONLY;
+}
+function wrapPdfInputReadError(cause, inputFile, inputLabel, allowedInputRoot) {
+    if (cause instanceof ComparePdfInputError_js_1.ComparePdfInputError) {
+        throw cause;
+    }
+    if (cause instanceof ComparePdfConfigurationError_js_1.ComparePdfConfigurationError) {
+        throw cause;
+    }
+    if (allowedInputRoot && isSymbolicLinkOpenError(cause)) {
+        throw new ComparePdfConfigurationError_js_1.ComparePdfConfigurationError(`${inputLabel} must resolve within allowedInputRoot: ${allowedInputRoot.displayPath}`, { cause });
+    }
+    if (isMissingPdfInputError(cause)) {
+        return new ComparePdfInputError_js_1.ComparePdfInputError(`PDF file not found: ${inputFile}`, { cause });
+    }
+    return new ComparePdfInputError_js_1.ComparePdfInputError(`Failed to read PDF file: ${inputFile}`, { cause });
+}
+function isMissingPdfInputError(cause) {
+    return cause instanceof Error && 'code' in cause && (cause.code === 'ENOENT' || cause.code === 'ENOTDIR');
+}
+function isSymbolicLinkOpenError(cause) {
+    return cause instanceof Error && 'code' in cause && (cause.code === 'ELOOP' || cause.code === 'EMLINK');
+}
+function assertStringPathWithinAllowedInputRoot(inputPath, inputLabel, allowedInputRoot) {
+    if (!allowedInputRoot) {
+        return;
+    }
+    if (!(0, securePath_js_1.isPathWithinRoot)(inputPath, allowedInputRoot.resolvedPath) &&
+        !(0, securePath_js_1.isPathWithinRoot)(inputPath, allowedInputRoot.canonicalPath)) {
+        throw new ComparePdfConfigurationError_js_1.ComparePdfConfigurationError(`${inputLabel} must resolve within allowedInputRoot: ${allowedInputRoot.displayPath}`);
+    }
+}

package/out/internal/pageComparisonPlan.d.ts

@@ -0,0 +1,4 @@
+import type { PageExclusion } from '../types/PageExclusion.js';
+import type { PageComparisonPlanEntry, RenderedPngPageOutput } from './types.js';
+export declare function buildPageComparisonPlan(actualPdfPngPages: readonly RenderedPngPageOutput[], expectedPdfPngPages: readonly RenderedPngPageOutput[], excludedAreas: readonly PageExclusion[]): PageComparisonPlanEntry[];
+export declare function buildPageNumberComparisonPlan(actualPageNumbers: readonly number[], expectedPageNumbers: readonly number[], excludedAreas: readonly PageExclusion[]): PageComparisonPlanEntry[];

package/out/internal/pageComparisonPlan.js

@@ -0,0 +1,35 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildPageComparisonPlan = buildPageComparisonPlan;
+exports.buildPageNumberComparisonPlan = buildPageNumberComparisonPlan;
+function buildPageComparisonPlan(actualPdfPngPages, expectedPdfPngPages, excludedAreas) {
+    const actualPagesByNumber = indexPagesByNumber(actualPdfPngPages);
+    const expectedPagesByNumber = indexPagesByNumber(expectedPdfPngPages);
+    return buildPageNumberComparisonPlan([...actualPagesByNumber.keys()], [...expectedPagesByNumber.keys()], excludedAreas).map((entry) => ({
+        ...entry,
+        actualPage: actualPagesByNumber.get(entry.pageNumber),
+        expectedPage: expectedPagesByNumber.get(entry.pageNumber),
+    }));
+}
+function buildPageNumberComparisonPlan(actualPageNumbers, expectedPageNumbers, excludedAreas) {
+    const exclusionsByPageNumber = indexPageExclusionsByNumber(excludedAreas);
+    const pageNumbers = new Set([...actualPageNumbers, ...expectedPageNumbers]);
+    return Array.from(pageNumbers)
+        .sort((leftPageNumber, rightPageNumber) => leftPageNumber - rightPageNumber)
+        .map((pageNumber) => ({
+        pageNumber,
+        pageExclusion: exclusionsByPageNumber.get(pageNumber),
+    }));
+}
+function indexPagesByNumber(pages) {
+    return new Map(pages.map((page) => [page.pageNumber, page]));
+}
+function indexPageExclusionsByNumber(excludedAreas) {
+    const exclusionsByPageNumber = new Map();
+    for (const excludedArea of excludedAreas) {
+        if (!exclusionsByPageNumber.has(excludedArea.pageNumber)) {
+            exclusionsByPageNumber.set(excludedArea.pageNumber, excludedArea);
+        }
+    }
+    return exclusionsByPageNumber;
+}

package/out/internal/renderOutputFolderGuards.d.ts

@@ -0,0 +1,22 @@
+import type { PdfRenderOptions } from '../types/PdfRenderOptions.js';
+/**
+ * Validates `pdfToPngConvertOptions.outputFolder` with the same sandbox-parity contract
+ * applied to `diffsOutputFolder` and `allowedInputRoot`:
+ *
+ * - rejects non-string / empty / whitespace-only values
+ * - rejects a path that already exists as a non-directory
+ * - rejects a path whose existing chain contains any symbolic link (closes CWE-59 /
+ *   CWE-61 redirect attacks where an attacker pre-plants a symlink so the renderer
+ *   writes intermediate PNGs to a target outside the intended workspace)
+ * - takes library ownership of leaf-directory creation for the resolved path AND the
+ *   `actual/` / `expected/` namespaces that `renderPdfPages` writes into, then re-asserts
+ *   each leaf is a real (non-symlink) directory. This closes the residual validate→render
+ *   TOCTOU window that the path walker cannot cover on its own: once a non-symlink
+ *   directory exists at every future write destination, an attacker can no longer plant a
+ *   symlink there between validation and the renderer's first write (CWE-367 / CWE-61).
+ *
+ * Returns the resolved absolute path so downstream renderer calls operate on a stable
+ * location, regardless of process cwd changes between configuration and render time.
+ * Returns `undefined` when no `outputFolder` was supplied (in-memory render).
+ */
+export declare function validateRenderOutputFolder(outputFolder: PdfRenderOptions['outputFolder']): string | undefined;

package/out/internal/renderOutputFolderGuards.js

@@ -0,0 +1,70 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateRenderOutputFolder = validateRenderOutputFolder;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const ComparePdfConfigurationError_js_1 = require("../errors/ComparePdfConfigurationError.js");
+const securePath_js_1 = require("./securePath.js");
+/**
+ * `renderPdfPages` namespaces the renderer output under these subdirectories so the
+ * actual and expected PDFs cannot collide on a shared `outputFileMaskFunc`. The validator
+ * pre-creates and lstat-verifies both leaves so the future write destinations cannot be
+ * replaced by symbolic links between validation and the renderer's first write.
+ */
+const RENDER_OUTPUT_NAMESPACES = ['actual', 'expected'];
+/**
+ * Validates `pdfToPngConvertOptions.outputFolder` with the same sandbox-parity contract
+ * applied to `diffsOutputFolder` and `allowedInputRoot`:
+ *
+ * - rejects non-string / empty / whitespace-only values
+ * - rejects a path that already exists as a non-directory
+ * - rejects a path whose existing chain contains any symbolic link (closes CWE-59 /
+ *   CWE-61 redirect attacks where an attacker pre-plants a symlink so the renderer
+ *   writes intermediate PNGs to a target outside the intended workspace)
+ * - takes library ownership of leaf-directory creation for the resolved path AND the
+ *   `actual/` / `expected/` namespaces that `renderPdfPages` writes into, then re-asserts
+ *   each leaf is a real (non-symlink) directory. This closes the residual validate→render
+ *   TOCTOU window that the path walker cannot cover on its own: once a non-symlink
+ *   directory exists at every future write destination, an attacker can no longer plant a
+ *   symlink there between validation and the renderer's first write (CWE-367 / CWE-61).
+ *
+ * Returns the resolved absolute path so downstream renderer calls operate on a stable
+ * location, regardless of process cwd changes between configuration and render time.
+ * Returns `undefined` when no `outputFolder` was supplied (in-memory render).
+ */
+function validateRenderOutputFolder(outputFolder) {
+    if (outputFolder === undefined) {
+        return undefined;
+    }
+    if (typeof outputFolder !== 'string' || outputFolder.trim() === '') {
+        throw new ComparePdfConfigurationError_js_1.ComparePdfConfigurationError('pdfToPngConvertOptions.outputFolder must be a non-empty string.');
+    }
+    const resolvedOutputFolder = (0, node_path_1.resolve)(outputFolder);
+    if ((0, node_fs_1.existsSync)(resolvedOutputFolder) && !(0, node_fs_1.statSync)(resolvedOutputFolder).isDirectory()) {
+        throw new ComparePdfConfigurationError_js_1.ComparePdfConfigurationError(`pdfToPngConvertOptions.outputFolder must point to a directory when it already exists: ${outputFolder}`);
+    }
+    (0, securePath_js_1.assertPathAndAncestorsAreNotSymbolicLinks)(resolvedOutputFolder, `pdfToPngConvertOptions.outputFolder must not traverse a symbolic link: ${(0, node_path_1.resolve)(outputFolder)}`);
+    ensureRealDirectory(resolvedOutputFolder);
+    for (const namespace of RENDER_OUTPUT_NAMESPACES) {
+        ensureRealDirectory((0, node_path_1.join)(resolvedOutputFolder, namespace));
+    }
+    return resolvedOutputFolder;
+}
+/**
+ * Creates `pathToCheck` as a real directory and re-asserts the on-disk entry is not a
+ * symbolic link. `mkdirSync({ recursive: true })` is a no-op when the target already
+ * exists, and crucially it follows existing symlinks-to-directories silently — the
+ * post-mkdir `lstat` is what catches a pre-planted symlink at this exact location.
+ */
+function ensureRealDirectory(pathToCheck) {
+    try {
+        (0, node_fs_1.mkdirSync)(pathToCheck, { recursive: true });
+    }
+    catch (cause) {
+        throw new ComparePdfConfigurationError_js_1.ComparePdfConfigurationError(`pdfToPngConvertOptions.outputFolder must point to a writable directory: ${pathToCheck}`, { cause });
+    }
+    const stats = (0, node_fs_1.lstatSync)(pathToCheck);
+    if (stats.isSymbolicLink() || !stats.isDirectory()) {
+        throw new ComparePdfConfigurationError_js_1.ComparePdfConfigurationError(`pdfToPngConvertOptions.outputFolder must not traverse a symbolic link: ${pathToCheck}`);
+    }
+}

package/out/internal/renderPdfPages.d.ts

@@ -0,0 +1,10 @@
+import type { PdfInput } from '../types/PdfInput.js';
+import type { RenderedPngPageOutput } from './types.js';
+import type { PdfToPngOptions, PngPageOutput } from 'pdf-to-png-converter';
+export type PlannedPdfPages = {
+    pageNumbers: number[];
+    prefetchedPages: Map<number, PngPageOutput>;
+};
+export declare function listRenderedPageNumbers(pdfFile: PdfInput, pdfToPngConvertOpts: PdfToPngOptions, sourceLabel: 'actual' | 'expected'): Promise<PlannedPdfPages>;
+export declare function renderPdfPages(pdfFile: PdfInput, pdfToPngConvertOpts: PdfToPngOptions, sourceLabel: 'actual' | 'expected'): Promise<RenderedPngPageOutput[]>;
+export declare function renderPdfPage(pdfFile: PdfInput, pdfToPngConvertOpts: PdfToPngOptions, pageNumber: number, sourceLabel: 'actual' | 'expected'): Promise<RenderedPngPageOutput | undefined>;