h17-sspdf 1.3.1 → 1.3.2

package/README.md

@@ -293,7 +293,7 @@ Any operation accepts `xMm` and `maxWidthMm` to override the theme margins for t
   fontSize: 10,                  // pt
   color: [0, 0, 0],              // RGB
   lineHeight: 1.4,               // multiplier
-  textTransform: 'uppercase',    // 'uppercase' | 'lowercase' | undefined
+  textTransform: 'upper',        // 'upper' | 'lower' | undefined
 
   // Spacing
   marginTopMm: 0,
@@ -468,6 +468,18 @@ Claude Code skills for generating PDFs and themes are available in the `skills/`
 
 ---
 
+## Security model
+
+SuperSimplePDF turns data into a document. The split between data and code matters for how you treat each input.
+
+- Source JSON is data. You can generate it from untrusted input. The engine reads it as a description of what to render, never as code.
+- Theme files are code. A `.js` theme is loaded with `require`, so it runs with your process privileges. Treat a theme like any other module you import. Do not load theme files you do not trust. Built-in themes referenced by name are safe.
+- Image paths are contained. The `image` operation reads files from disk via `src`. To stop an untrusted source document from reading arbitrary files into a PDF, `src` must be a relative path that stays inside the working directory. Absolute paths, parent directory traversal with `..`, and null bytes are rejected.
+
+The engine has no network access and no runtime dependencies in the base install, so a source document cannot trigger an outbound request. The optional chart plugin adds the `canvas` native module, which renders locally and does not phone home.
+
+If you find a security issue, see SECURITY.md.
+
 ## Constraints
 
 - Page format defaults to A4; custom dimensions supported via `pageWidthMm`/`pageHeightMm` (e.g. 16:9 presentations)

package/core/image-utils.js

@@ -1,5 +1,10 @@
 "use strict";
 
+const fs = require("fs");
+const path = require("path");
+
+const MAX_IMAGE_SIZE_BYTES = 50 * 1024 * 1024;
+
 /**
  * Read native width/height from PNG or JPEG buffer.
  * Returns { width, height, format } or throws.
@@ -63,6 +68,62 @@ function getImageDimensions(buf) {
   throw new Error("Unsupported image format. Only PNG and JPEG are supported.");
 }
 
+/**
+ * Resolve and validate an image `src` path.
+ * Only relative paths inside the current working directory are allowed.
+ * Returns the absolute resolved path.
+ *
+ * @param {string} src - Relative path from source JSON
+ * @param {string} [index] - Operation index for error messages
+ * @returns {string}
+ */
+function resolveImagePath(src, index) {
+  const prefix = index ? `Operation ${index} (image) ` : "image ";
+  if (!src || typeof src !== "string") {
+    throw new Error(`${prefix}missing "src" field`);
+  }
+  if (path.isAbsolute(src) || src.includes("\0")) {
+    throw new Error(`${prefix}"src" must be a relative path: "${src}"`);
+  }
+  const imageBaseDir = path.resolve(process.cwd());
+  const resolvedPath = path.resolve(imageBaseDir, src);
+  if (resolvedPath !== imageBaseDir && !resolvedPath.startsWith(imageBaseDir + path.sep)) {
+    throw new Error(`${prefix}"src" escapes the working directory: "${src}"`);
+  }
+  return resolvedPath;
+}
+
+/**
+ * Read an image file with size limits.
+ *
+ * @param {string} resolvedPath
+ * @param {string} [index]
+ * @param {number} [maxSizeBytes]
+ * @returns {Buffer}
+ */
+function readImageFile(resolvedPath, index, maxSizeBytes = MAX_IMAGE_SIZE_BYTES) {
+  const prefix = index ? `Operation ${index} (image) ` : "image ";
+  let stats;
+  try {
+    stats = fs.statSync(resolvedPath);
+  } catch (err) {
+    throw new Error(`${prefix}could not stat file "${resolvedPath}": ${err.message}`);
+  }
+  if (stats.size > maxSizeBytes) {
+    throw new Error(`${prefix}file exceeds ${maxSizeBytes} bytes: "${resolvedPath}"`);
+  }
+  let buf;
+  try {
+    buf = fs.readFileSync(resolvedPath);
+  } catch (err) {
+    throw new Error(`${prefix}could not read file "${resolvedPath}": ${err.message}`);
+  }
+  if (!buf || buf.length === 0) {
+    throw new Error(`${prefix}file is empty: "${resolvedPath}"`);
+  }
+  return buf;
+}
+
 /**
  * Resolve display dimensions from source operation and content bounds.
  *
@@ -109,4 +170,10 @@ function resolveImageSize(op, nativeW, nativeH, contentWidthMm) {
   return { widthMm: contentWidthMm, heightMm: contentWidthMm * ratio };
 }
 
-module.exports = { getImageDimensions, resolveImageSize };
+module.exports = {
+  getImageDimensions,
+  resolveImageSize,
+  resolveImagePath,
+  readImageFile,
+  MAX_IMAGE_SIZE_BYTES,
+};

package/core/pdf-core.js

@@ -461,12 +461,12 @@ class PDFCore {
     );
     const baseline = y + baselineOffsetMm;
 
-    if (payload.leftText) {
+    if (payload.leftText != null) {
       this.applyTextStyle(leftStyle);
       this.doc.text(applyTextTransform(String(payload.leftText), leftStyle.textTransform), xLeft, baseline);
     }
 
-    if (payload.rightText) {
+    if (payload.rightText != null) {
       this.applyTextStyle(rightStyle);
       this.doc.text(applyTextTransform(String(payload.rightText), rightStyle.textTransform), xRight, baseline, { align: "right" });
     }
@@ -967,7 +967,10 @@ class PDFCore {
 
   _resolveColor(color, fallback) {
     if (Array.isArray(color) && color.length === 3) {
-      return color;
+      return color.map((c) => {
+        const n = Number(c) || 0;
+        return Math.max(0, Math.min(255, Math.round(n)));
+      });
     }
     return fallback;
   }

package/core/render-document.js

@@ -1,11 +1,9 @@
-const fs = require("fs");
-const path = require("path");
 const { PDFCore, getStyleMarginsMm, getTextPaddingMm, applyTextTransform } = require("./pdf-core");
 const { pxToMm, resolveLineHeightMm } = require("./units");
 const { registerThemeFonts } = require("./font-registry");
 const { getPlugin, hasPlugin } = require("./plugin-registry");
 const { validateSource, validateTheme, validateSourceAgainstTheme } = require("./validate");
-const { getImageDimensions, resolveImageSize } = require("./image-utils");
+const { getImageDimensions, resolveImageSize, resolveImagePath, readImageFile } = require("./image-utils");
 
 /**
  * Render a document by executing labeled operations.
@@ -754,31 +752,11 @@ function executeOperation(ctx) {
     const bounds = getHorizontalBounds(core, templateBypassMargins);
     const contentWidthMm = bounds.right - bounds.left;
 
-    // Read image file
-    const srcPath = operation.src;
-    if (!srcPath) {
-      throw new Error(`Operation ${index} (image) missing "src" field`);
-    }
-    // Containment: src must be a relative path under the working directory.
-    // Blocks absolute paths and ../ traversal so an untrusted source document
-    // cannot read arbitrary files (e.g. /etc/passwd, ../../app/.env) into the PDF.
-    if (path.isAbsolute(srcPath) || srcPath.includes("\0")) {
-      throw new Error(`Operation ${index} (image) "src" must be a relative path: "${srcPath}"`);
-    }
-    const imageBaseDir = path.resolve(process.cwd());
-    const resolvedPath = path.resolve(imageBaseDir, srcPath);
-    if (resolvedPath !== imageBaseDir && !resolvedPath.startsWith(imageBaseDir + path.sep)) {
-      throw new Error(`Operation ${index} (image) "src" escapes the working directory: "${srcPath}"`);
-    }
-    let buf;
-    try {
-      buf = fs.readFileSync(resolvedPath);
-    } catch (err) {
-      throw new Error(`Operation ${index} (image) could not read file "${resolvedPath}": ${err.message}`);
-    }
-    if (!buf || buf.length === 0) {
-      throw new Error(`Operation ${index} (image) file is empty: "${resolvedPath}"`);
-    }
+    // Read image file with containment and size limits.
+    // Containment blocks absolute paths and ../ traversal so an untrusted source
+    // document cannot read arbitrary files (e.g. /etc/passwd, ../../app/.env).
+    const resolvedPath = resolveImagePath(operation.src, index);
+    const buf = readImageFile(resolvedPath, index);
     let imgInfo;
     try {
       imgInfo = getImageDimensions(buf);
@@ -1145,15 +1123,8 @@ function estimateOperationHeight(ctx) {
     let imgHeightMm = 80; // fallback
     if (operation.src) {
       try {
-        if (path.isAbsolute(operation.src) || operation.src.includes("\0")) {
-          throw new Error(`image "src" must be a relative path: "${operation.src}"`);
-        }
-        const imageBaseDir = path.resolve(process.cwd());
-        const resolvedPath = path.resolve(imageBaseDir, operation.src);
-        if (resolvedPath !== imageBaseDir && !resolvedPath.startsWith(imageBaseDir + path.sep)) {
-          throw new Error(`image "src" escapes the working directory: "${operation.src}"`);
-        }
-        const buf = fs.readFileSync(resolvedPath);
+        const resolvedPath = resolveImagePath(operation.src, index);
+        const buf = readImageFile(resolvedPath, index);
         const imgInfo = getImageDimensions(buf);
         const resolved = resolveImageSize(operation, imgInfo.width, imgInfo.height, contentWidthMm - padding.left - padding.right);
         imgHeightMm = resolved.heightMm;

package/core/shapes.js

@@ -15,7 +15,7 @@
 
 'use strict';
 
-const PT_TO_MM = 0.3528;
+const { PT_TO_MM } = require('./units');
 
 // Vertical center: when pt is given, use half the font height; otherwise fall back to 1*s
 function mid(y, s, pt) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "h17-sspdf",
-  "version": "1.3.1",
+  "version": "1.3.2",
   "description": "Declarative PDF engine - define layout once, feed it JSON, get consistent PDFs",
   "main": "index.js",
   "author": "Hugo Palma",