@n0zer0d4y/vulcan-file-ops 1.2.13 → 1.3.0

package/dist/utils/html-image-sanitizer.js

@@ -0,0 +1,478 @@
+/**
+ * Image sanitization for HTML that is converted to PDF/DOCX (VFO-13).
+ *
+ * Only inline `data:image/...;base64,` images are allowed into generated
+ * documents. Every other image reference (relative/absolute paths, `file:`,
+ * `http(s):`, malformed data URLs, `srcset`, ...) is replaced with the image's
+ * `alt` text, because:
+ *   - pdfmake's browser build rejects such images inside its own promise chain,
+ *     which previously hung the write and crashed the server (unhandled
+ *     rejection), and
+ *   - html-to-docx downloads `http(s):` image URLs (server-side request).
+ *
+ * The sanitizer is a small tokenizer that follows the WHATWG HTML tag and
+ * attribute tokenization rules. It deliberately over-approximates: every
+ * `<img`, `<image` and `<source` start tag anywhere in the input (including
+ * inside comments, attribute values or raw-text elements) is rewritten, so a
+ * downstream parser can never see an image tag that was not sanitized. Image
+ * tags are re-serialized canonically (first attribute wins, values re-quoted)
+ * so the downstream parser sees exactly the attributes that were validated.
+ */
+import zlib from "zlib";
+import { MAX_DECODED_IMAGE_PIXELS, MAX_EMBEDDED_IMAGE_BYTES, } from "./limits.js";
+export const ALL_EMBEDDABLE_IMAGE_TYPES = [
+    "png",
+    "jpeg",
+    "gif",
+    "webp",
+    "bmp",
+];
+const DATA_URL_PREFIX_RE = /^data:image\/(png|jpe?g|gif|webp|bmp);base64,/i;
+const BASE64_BODY_RE = /^[A-Za-z0-9+/]*={0,2}$/;
+const HTML_WHITESPACE_RE = /[\t\n\f\r ]+/g;
+function hasSignature(bytes, type) {
+    switch (type) {
+        case "png":
+            return (bytes.length >= 8 &&
+                bytes
+                    .subarray(0, 8)
+                    .equals(Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a])));
+        case "jpeg":
+            return (bytes.length >= 3 &&
+                bytes[0] === 0xff &&
+                bytes[1] === 0xd8 &&
+                bytes[2] === 0xff);
+        case "gif": {
+            const sig = bytes.subarray(0, 6).toString("latin1");
+            return sig === "GIF87a" || sig === "GIF89a";
+        }
+        case "webp":
+            return (bytes.length >= 12 &&
+                bytes.subarray(0, 4).toString("latin1") === "RIFF" &&
+                bytes.subarray(8, 12).toString("latin1") === "WEBP");
+        case "bmp":
+            return bytes.length >= 2 && bytes[0] === 0x42 && bytes[1] === 0x4d;
+    }
+}
+/**
+ * Validate an image source and return its canonical form
+ * (`data:image/<type>;base64,<base64 without whitespace>`), or `null` if the
+ * source must not be embedded.
+ */
+export function normalizeEmbeddableImageSrc(src, options = {}) {
+    if (typeof src !== "string")
+        return null;
+    const memo = options.memo;
+    if (memo?.has(src))
+        return memo.get(src) ?? null;
+    const result = normalizeImageSrcUncached(src, options);
+    memo?.set(src, result);
+    if (result !== null)
+        memo?.set(result, result);
+    return result;
+}
+function normalizeImageSrcUncached(src, options) {
+    const allowedTypes = options.allowedTypes ?? ALL_EMBEDDABLE_IMAGE_TYPES;
+    const maxBytes = options.maxImageBytes ?? MAX_EMBEDDED_IMAGE_BYTES;
+    // Cheap upper bound before any further work on very large strings:
+    // base64 is 4 chars per 3 bytes; allow generous slack for whitespace.
+    if (src.length > Math.ceil(maxBytes / 3) * 4 * 2 + 1024)
+        return null;
+    const trimmed = src.replace(/^[\t\n\f\r ]+|[\t\n\f\r ]+$/g, "");
+    const prefix = DATA_URL_PREFIX_RE.exec(trimmed);
+    if (!prefix)
+        return null;
+    const declared = prefix[1].toLowerCase();
+    const type = declared === "jpg" ? "jpeg" : declared;
+    if (!allowedTypes.includes(type))
+        return null;
+    const body = trimmed.slice(prefix[0].length).replace(HTML_WHITESPACE_RE, "");
+    if (body.length === 0 || body.length % 4 !== 0)
+        return null;
+    if (!BASE64_BODY_RE.test(body))
+        return null;
+    const padding = body.endsWith("==") ? 2 : body.endsWith("=") ? 1 : 0;
+    const decodedBytes = (body.length / 4) * 3 - padding;
+    if (decodedBytes > maxBytes)
+        return null;
+    // The declared type must match the actual content.
+    const head = Buffer.from(body.slice(0, 16), "base64");
+    if (!hasSignature(head, type))
+        return null;
+    if (type === "png" && options.verifyPngForPdfkit) {
+        const maxPixels = options.maxDecodedPixels ?? MAX_DECODED_IMAGE_PIXELS;
+        if (!isPngSafeForPdfkit(Buffer.from(body, "base64"), maxPixels)) {
+            return null;
+        }
+    }
+    return `data:image/${type};base64,${body}`;
+}
+// ---------------------------------------------------------------------------
+// PNG validation for pdfkit
+// ---------------------------------------------------------------------------
+const PNG_ALLOWED_BIT_DEPTHS = {
+    0: [1, 2, 4, 8, 16], // greyscale
+    2: [8, 16], // truecolor
+    3: [1, 2, 4, 8], // indexed
+    4: [8, 16], // greyscale + alpha
+    6: [8, 16], // truecolor + alpha
+};
+/**
+ * pdfkit (bundled in pdfmake) embeds most PNGs as-is, but PNGs with an alpha
+ * channel, indexed transparency (tRNS) or interlacing are decoded with png-js
+ * inside an asynchronous zlib callback. Any error there (corrupt deflate
+ * stream, invalid scanline filter) is thrown from that callback as an
+ * uncaught exception, which terminates the server. Such PNGs are therefore
+ * decoded here first, synchronously and with Node's zlib, replicating png-js'
+ * scanline walk, so only images that png-js can decode without throwing are
+ * embedded. Also bounds the memory png-js would allocate.
+ */
+export function isPngSafeForPdfkit(png, maxPixels) {
+    try {
+        let pos = 8;
+        let ihdr = null;
+        let hasPalette = false;
+        let indexedTransparency = false;
+        const idat = [];
+        let sawEnd = false;
+        while (!sawEnd) {
+            if (pos + 8 > png.length)
+                return false;
+            const length = png.readUInt32BE(pos);
+            const type = png.toString("latin1", pos + 4, pos + 8);
+            pos += 8;
+            if (length > 0x7fffffff || pos + length + 4 > png.length)
+                return false;
+            const data = png.subarray(pos, pos + length);
+            if (ihdr === null && type !== "IHDR")
+                return false;
+            switch (type) {
+                case "IHDR":
+                    if (ihdr !== null || length !== 13)
+                        return false;
+                    ihdr = {
+                        width: data.readUInt32BE(0),
+                        height: data.readUInt32BE(4),
+                        bits: data[8],
+                        colorType: data[9],
+                        interlace: data[12],
+                    };
+                    if (data[10] !== 0 || data[11] !== 0)
+                        return false;
+                    break;
+                case "PLTE":
+                    hasPalette = length > 0 && length % 3 === 0;
+                    break;
+                case "IDAT":
+                    idat.push(data);
+                    break;
+                case "tRNS":
+                    if (ihdr?.colorType === 3)
+                        indexedTransparency = true;
+                    break;
+                case "IEND":
+                    sawEnd = true;
+                    break;
+            }
+            pos += length + 4; // data + CRC
+        }
+        if (!ihdr || idat.length === 0)
+            return false;
+        const { width, height, bits, colorType, interlace } = ihdr;
+        if (width < 1 || height < 1 || width > 0x7fffffff || height > 0x7fffffff) {
+            return false;
+        }
+        const allowedBits = PNG_ALLOWED_BIT_DEPTHS[colorType];
+        if (!allowedBits || !allowedBits.includes(bits))
+            return false;
+        if (interlace !== 0 && interlace !== 1)
+            return false;
+        if (colorType === 3 && !hasPalette)
+            return false;
+        const hasAlpha = colorType === 4 || colorType === 6;
+        const needsDecode = hasAlpha || indexedTransparency || interlace === 1;
+        if (!needsDecode)
+            return true; // embedded verbatim, never decoded
+        if (width * height > maxPixels)
+            return false;
+        // Same arithmetic as png-js (including its fractional pixelBytes).
+        const colors = colorType === 2 || colorType === 6 ? 3 : 1;
+        const pixelBytes = (bits * (colors + (hasAlpha ? 1 : 0))) / 8;
+        const passes = interlace === 1
+            ? [
+                [0, 0, 8, 8],
+                [4, 0, 8, 8],
+                [0, 4, 4, 8],
+                [2, 0, 4, 4],
+                [0, 2, 2, 4],
+                [1, 0, 2, 2],
+                [0, 1, 1, 2],
+            ]
+            : [[0, 0, 1, 1]];
+        let expected = 0;
+        for (const [x0, y0, dx, dy] of passes) {
+            const w = Math.ceil((width - x0) / dx);
+            const h = Math.ceil((height - y0) / dy);
+            if (h > 0)
+                expected += h * (1 + Math.max(0, Math.ceil(pixelBytes * w)));
+        }
+        const compressed = Buffer.concat(idat);
+        const { buffer: inflated, engine } = zlib.inflateSync(compressed, {
+            info: true,
+            maxOutputLength: expected + 1024,
+        });
+        // Reject trailing data after the zlib stream (strict parity with pako).
+        if (engine.bytesWritten !== compressed.length)
+            return false;
+        // Walk the scanlines exactly like png-js and check every filter byte.
+        let p = 0;
+        const length = inflated.length;
+        for (const [x0, y0, dx, dy] of passes) {
+            const w = Math.ceil((width - x0) / dx);
+            const h = Math.ceil((height - y0) / dy);
+            const rowBytes = Math.max(0, Math.ceil(pixelBytes * w));
+            for (let row = 0; row < h && p < length; row++) {
+                if (inflated[p++] > 4)
+                    return false;
+                p += rowBytes;
+            }
+        }
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+const isTagWhitespace = (ch) => ch === "\t" || ch === "\n" || ch === "\f" || ch === "\r" || ch === " ";
+/**
+ * Parse the attributes of a start tag whose name ends at `pos`.
+ * Follows the HTML tokenizer states "before attribute name" through
+ * "after attribute value (quoted)".
+ */
+function parseTagAttributes(html, pos) {
+    const attributes = new Map();
+    const len = html.length;
+    let i = pos;
+    while (i < len) {
+        // Before attribute name: skip whitespace and stray solidus.
+        const ch = html[i];
+        if (isTagWhitespace(ch) || ch === "/") {
+            i++;
+            continue;
+        }
+        if (ch === ">") {
+            return { attributes, end: i + 1 };
+        }
+        // Attribute name (a leading "=" is part of the name per spec).
+        let nameStart = i;
+        i++;
+        while (i < len) {
+            const c = html[i];
+            if (isTagWhitespace(c) || c === "/" || c === ">" || c === "=")
+                break;
+            i++;
+        }
+        const name = html.slice(nameStart, i).toLowerCase();
+        // After attribute name.
+        while (i < len && isTagWhitespace(html[i]))
+            i++;
+        let value = "";
+        if (i < len && html[i] === "=") {
+            i++;
+            while (i < len && isTagWhitespace(html[i]))
+                i++;
+            if (i >= len)
+                break;
+            const q = html[i];
+            if (q === '"' || q === "'") {
+                const close = html.indexOf(q, i + 1);
+                if (close === -1) {
+                    i = len; // EOF inside quoted value
+                    break;
+                }
+                value = html.slice(i + 1, close);
+                i = close + 1;
+            }
+            else if (q !== ">") {
+                const valueStart = i;
+                while (i < len && !isTagWhitespace(html[i]) && html[i] !== ">")
+                    i++;
+                value = html.slice(valueStart, i);
+            }
+        }
+        if (!attributes.has(name))
+            attributes.set(name, value);
+    }
+    // EOF inside the tag: per spec the tag is dropped.
+    return { attributes, end: -1 };
+}
+const NAMED_REFS = {
+    amp: "&",
+    lt: "<",
+    gt: ">",
+    quot: '"',
+    apos: "'",
+    nbsp: " ",
+};
+/** Decode the character references that matter for alt text. */
+function decodeBasicEntities(text) {
+    return text.replace(/&(#[xX][0-9a-fA-F]{1,6}|#[0-9]{1,7}|[a-zA-Z]+);/g, (match, ref) => {
+        if (ref[0] === "#") {
+            const code = ref[1] === "x" || ref[1] === "X"
+                ? parseInt(ref.slice(2), 16)
+                : parseInt(ref.slice(1), 10);
+            if (!Number.isFinite(code) ||
+                code <= 0 ||
+                code > 0x10ffff ||
+                (code >= 0xd800 && code <= 0xdfff)) {
+                return "�";
+            }
+            return String.fromCodePoint(code);
+        }
+        const named = NAMED_REFS[ref.toLowerCase()];
+        return named ?? match;
+    });
+}
+export function escapeHtmlText(text) {
+    return text
+        .replace(/&/g, "&amp;")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;")
+        .replace(/"/g, "&quot;")
+        .replace(/'/g, "&#39;");
+}
+const SAFE_ATTR_NAME_RE = /^[a-zA-Z_:][-a-zA-Z0-9_:.]*$/;
+/** Attributes that can make a converter fetch or reference an image. */
+const IMAGE_SOURCE_ATTRS = new Set(["src", "href", "xlink:href"]);
+const ALWAYS_DROPPED_ATTRS = new Set([
+    "srcset",
+    "data-src",
+    "data-srcset",
+    "lowsrc",
+    "dynsrc",
+    "longdesc",
+    "usemap",
+    "imagesizes",
+    "imagesrcset",
+]);
+function serializeTag(tagName, attributes) {
+    let out = `<${tagName}`;
+    for (const [name, value] of attributes) {
+        if (!SAFE_ATTR_NAME_RE.test(name))
+            continue;
+        // Keep character references as written (they decode identically when
+        // re-parsed inside a double-quoted value); only the quote must be escaped.
+        out += ` ${name}="${value.replace(/"/g, "&quot;")}"`;
+    }
+    return out + ">";
+}
+function sanitizeImageTag(tagName, attributes, options) {
+    const kept = new Map();
+    let hasSource = false;
+    for (const [name, value] of attributes) {
+        if (ALWAYS_DROPPED_ATTRS.has(name))
+            continue;
+        if (IMAGE_SOURCE_ATTRS.has(name)) {
+            const normalized = normalizeEmbeddableImageSrc(value, options);
+            if (normalized === null)
+                continue;
+            kept.set(name, normalized);
+            hasSource = true;
+            continue;
+        }
+        kept.set(name, value);
+    }
+    // A disallowed source is not "partially" kept: if any source attribute was
+    // rejected, the whole image is replaced (avoids parser disagreements over
+    // which of src/href wins).
+    const rejectedSource = [...attributes.keys()].some((name) => IMAGE_SOURCE_ATTRS.has(name) && !kept.has(name));
+    if (hasSource && !rejectedSource) {
+        return serializeTag(tagName, kept);
+    }
+    const alt = attributes.get("alt");
+    return alt ? escapeHtmlText(decodeBasicEntities(alt)) : "";
+}
+function sanitizeSourceTag(attributes) {
+    const kept = new Map();
+    for (const [name, value] of attributes) {
+        if (name === "src" || name === "srcset" || ALWAYS_DROPPED_ATTRS.has(name)) {
+            continue;
+        }
+        kept.set(name, value);
+    }
+    return serializeTag("source", kept);
+}
+const IMAGE_TAG_START_RE = /<(img|image|source)(?=[\t\n\f\r />]|$)/giy;
+/**
+ * Rewrite every image-bearing tag in `html` so that only validated inline
+ * `data:` images remain. Non-embeddable images are replaced with their
+ * escaped `alt` text (or removed when there is none).
+ */
+export function sanitizeHtmlImages(html, options = {}) {
+    let out = "";
+    let last = 0;
+    let searchFrom = 0;
+    while (searchFrom < html.length) {
+        const lt = html.indexOf("<", searchFrom);
+        if (lt === -1)
+            break;
+        IMAGE_TAG_START_RE.lastIndex = lt;
+        const match = IMAGE_TAG_START_RE.exec(html);
+        if (!match) {
+            searchFrom = lt + 1;
+            continue;
+        }
+        const tagName = match[1].toLowerCase();
+        const parsed = parseTagAttributes(html, lt + match[0].length);
+        out += html.slice(last, lt);
+        if (parsed.end === -1) {
+            // Unterminated tag at end of input: drop it.
+            last = html.length;
+            break;
+        }
+        out +=
+            tagName === "source"
+                ? sanitizeSourceTag(parsed.attributes)
+                : sanitizeImageTag(tagName, parsed.attributes, options);
+        last = parsed.end;
+        searchFrom = parsed.end;
+    }
+    return out + html.slice(last);
+}
+/**
+ * Defense in depth for the PDF path: walk a pdfmake content tree and replace
+ * any `image` node whose source is not an embeddable data URL (e.g. one that
+ * entered through html-to-pdfmake's `data-pdfmake` attribute) with empty text.
+ * Mutates and returns the tree.
+ */
+export function scrubPdfmakeImages(content, options = {}) {
+    const seen = new WeakSet();
+    const visit = (node) => {
+        if (Array.isArray(node)) {
+            if (seen.has(node))
+                return node;
+            seen.add(node);
+            for (let i = 0; i < node.length; i++)
+                node[i] = visit(node[i]);
+            return node;
+        }
+        if (node && typeof node === "object") {
+            if (seen.has(node))
+                return node;
+            seen.add(node);
+            const record = node;
+            if (Object.prototype.hasOwnProperty.call(record, "image")) {
+                const normalized = normalizeEmbeddableImageSrc(record.image, options);
+                if (normalized === null)
+                    return { text: "" };
+                record.image = normalized;
+            }
+            for (const key of Object.keys(record)) {
+                record[key] = visit(record[key]);
+            }
+        }
+        return node;
+    };
+    return visit(content);
+}
+//# sourceMappingURL=html-image-sanitizer.js.map

package/dist/utils/html-to-document.js

@@ -9,6 +9,8 @@
  * - html-to-docx: HTML → DOCX conversion
  * - jsdom: DOM emulation for Node.js
  */
+import { sanitizeHtmlImages, scrubPdfmakeImages, } from "./html-image-sanitizer.js";
+import { PDF_GENERATION_TIMEOUT_MS } from "./limits.js";
 // Lazy-loaded libraries (imported only when needed)
 let pdfMake = null;
 let pdfFonts = null;
@@ -61,10 +63,13 @@ function sanitizeHTMLForDOCX(html) {
         // Common typographic characters
         .replace(/—/g, "—") // Em dash
         .replace(/–/g, "–") // En dash
-        .replace(/"/g, "“") // Left double quote
-        .replace(/"/g, "”") // Right double quote
-        .replace(/'/g, "‘") // Left single quote
-        .replace(/'/g, "’") // Right single quote
+        // Curly quotes only (written as escapes so they cannot be "normalized"
+        // into ASCII quotes, which previously turned every quoted attribute
+        // value - e.g. src="data:..." or style="..." - into garbage).
+        .replace(/“/g, "“") // Left double quote
+        .replace(/”/g, "”") // Right double quote
+        .replace(/‘/g, "‘") // Left single quote
+        .replace(/’/g, "’") // Right single quote
         .replace(/…/g, "…") // Ellipsis
         // Degree and other symbols
         .replace(/°/g, "°") // Degree
@@ -124,8 +129,14 @@ export async function htmlToPDF(htmlContent, options = {}) {
     }
     // Create DOM window for html-to-pdfmake
     const { window } = new jsdom("");
+    // Only validated inline data: images may reach pdfmake (VFO-13).
+    const imageOptions = {
+        ...PDF_IMAGE_OPTIONS,
+        memo: new Map(),
+    };
+    const safeHTML = sanitizeHtmlImages(htmlContent, imageOptions);
     // Convert HTML to PDFMake format with styling
-    const converted = htmlToPdfmake(htmlContent, {
+    const converted = htmlToPdfmake(safeHTML, {
         window,
         defaultStyles: {
             // Headings with colors
@@ -227,16 +238,66 @@ export async function htmlToPDF(htmlContent, options = {}) {
         pageSize: "A4",
         pageMargins: [40, 60, 40, 60],
     };
-    // Generate PDF and return as Buffer
+    // Defense in depth: html-to-pdfmake can also emit image nodes from
+    // `data-pdfmake` attributes, so validate the final tree as well.
+    scrubPdfmakeImages(converted, imageOptions);
+    return renderPdfBuffer(docDefinition, options.timeoutMs ?? PDF_GENERATION_TIMEOUT_MS);
+}
+/**
+ * pdfkit (used by pdfmake) can only embed PNG and JPEG images; anything else
+ * would make the whole PDF fail, so other formats degrade to alt text.
+ */
+const PDF_IMAGE_OPTIONS = {
+    allowedTypes: ["png", "jpeg"],
+    verifyPngForPdfkit: true,
+};
+const DOCX_IMAGE_OPTIONS = {};
+function toError(error) {
+    if (error instanceof Error)
+        return error;
+    return new Error(typeof error === "string" ? error : String(error));
+}
+/**
+ * Render a pdfmake document definition to a Buffer.
+ *
+ * pdfmake 0.2.x's `getBuffer(cb)` builds the document inside an internal
+ * promise chain: if building fails (e.g. an invalid image), the callback is
+ * never called and the rejection is unhandled, which hangs the write and
+ * terminates Node (VFO-13). pdfmake exposes no promise API to catch that, so
+ * instead we use `getStream()` without a callback: it builds the PDFKit
+ * document synchronously (errors are thrown to us here) and skips pdfmake's
+ * URL resolver entirely (no network fetches of fonts/images). The stream is
+ * then drained with error handling and a hard timeout, so this promise always
+ * settles.
+ */
+function renderPdfBuffer(docDefinition, timeoutMs) {
     return new Promise((resolve, reject) => {
+        let settled = false;
+        const timer = setTimeout(() => {
+            settle(new Error(`PDF generation timed out after ${timeoutMs} ms`));
+        }, timeoutMs);
+        timer.unref?.();
+        function settle(error, buffer) {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            if (error)
+                reject(error);
+            else
+                resolve(buffer);
+        }
         try {
             const pdfDoc = pdfMake.createPdf(docDefinition);
-            pdfDoc.getBuffer((buffer) => {
-                resolve(buffer);
-            });
+            const stream = pdfDoc.getStream();
+            const chunks = [];
+            stream.on("data", (chunk) => chunks.push(chunk));
+            stream.on("end", () => settle(null, Buffer.concat(chunks)));
+            stream.on("error", (error) => settle(toError(error)));
+            stream.end();
         }
         catch (error) {
-            reject(error);
+            settle(toError(error));
         }
     });
 }
@@ -262,8 +323,11 @@ export async function htmlToDOCX(htmlContent, options = {}) {
         const module = await import("@turbodocx/html-to-docx");
         HTMLtoDOCX = module.default || module;
     }
+    // Only validated inline data: images may reach html-to-docx, which would
+    // otherwise download http(s) image URLs (VFO-13).
+    const imageSafeHTML = sanitizeHtmlImages(htmlContent, DOCX_IMAGE_OPTIONS);
     // Sanitize HTML to handle problematic Unicode characters
-    const sanitizedHTML = sanitizeHTMLForDOCX(htmlContent);
+    const sanitizedHTML = sanitizeHTMLForDOCX(imageSafeHTML);
     // DOCX generation options
     const docxOptions = {
         title: options.title || "Document",