@xenterprises/fastify-xpdf 1.0.0

package/SECURITY.md

@@ -0,0 +1,417 @@
+# Security Policy
+
+## Overview
+
+xPDF is a Fastify plugin for PDF generation and manipulation. This document outlines the security considerations, best practices, and guidelines for using xPDF safely in production environments.
+
+## Security Model
+
+### What xPDF Does Safely
+- **PDF Generation**: HTML/Markdown rendered in isolated Puppeteer context - user code never executes
+- **Form Operations**: PDF manipulation using pdf-lib library (pure JavaScript, no native bindings)
+- **Input Validation**: All inputs are validated before processing
+- **Storage**: Optional xStorage integration uses S3-compatible APIs with access control
+
+### Attack Surface
+The main security concerns are:
+
+1. **Puppeteer Sandboxing** - Browser process isolation
+2. **Untrusted HTML/Markdown** - User-supplied content rendering
+3. **PDF Resource Consumption** - DoS potential with large operations
+4. **Storage Access** - Cloud storage credential handling
+
+## Security Guidelines
+
+### 1. Puppeteer Sandboxing
+
+**Default Configuration**
+```javascript
+args = ["--no-sandbox", "--disable-setuid-sandbox"]
+```
+
+**Why**: Linux environments often need these flags for Puppeteer to run. This reduces isolation.
+
+**Risk Level**: Medium in containerized environments, Low in Docker with resource limits
+
+**Mitigation Strategies**:
+
+#### Option A: Use Docker (Recommended)
+```dockerfile
+FROM node:20-alpine
+RUN apk add --no-cache chromium
+ENV PUPPETEER_SKIP_DOWNLOAD=true
+ENV PUPPETEER_EXECUTABLE_PATH=/usr/bin/chromium-browser
+WORKDIR /app
+COPY . .
+RUN npm install
+CMD ["npm", "start"]
+```
+
+Docker provides OS-level isolation. No additional Puppeteer args needed.
+
+#### Option B: Enable Sandboxing on Supported Systems
+```javascript
+await fastify.register(xPDF, {
+  // Remove no-sandbox args for systems that support it
+  args: [],
+  // or use only essential args
+  args: ["--disable-dev-shm-usage"],
+});
+```
+
+#### Option C: Run in Virtual Machine/Separate Process
+- Run Puppeteer in a separate, isolated VM
+- Use IPC for communication
+- Limit resources at OS level
+
+**Recommendation**: Use Option A (Docker) for production. It's the simplest and most secure.
+
+---
+
+### 2. HTML/Markdown Input Handling
+
+**Current Behavior**: xPDF passes HTML directly to Puppeteer without sanitization.
+
+**Why This is Safe**:
+- PDFs are static output - no JavaScript execution in the PDF
+- Puppeteer runs in isolated process
+- User code never runs in your application
+
+**When to Sanitize**:
+You should sanitize if:
+- HTML/Markdown comes from untrusted users
+- You generate HTML from user input and pass to xPDF
+- Content includes user-uploaded files or links
+
+**Sanitization Example**:
+```javascript
+import DOMPurify from 'isomorphic-dompurify';
+
+// Sanitize user HTML before passing to xPDF
+const userHtml = '<img src="x" onerror="alert(1)">';
+const safeHtml = DOMPurify.sanitize(userHtml);
+
+const pdf = await fastify.xPDF.generateFromHtml(safeHtml);
+```
+
+**Markdown Safety**:
+The `marked` library is designed for safe HTML output. However:
+- Unsafe markdown options can enable HTML: `{ breaks: true, gfm: true }`
+- User-provided URLs in markdown could be malicious
+- Sanitize output if markdown comes from untrusted sources
+
+```javascript
+import { marked } from 'marked';
+import DOMPurify from 'isomorphic-dompurify';
+
+const userMarkdown = '# [Click here](javascript:alert(1))';
+const html = marked(userMarkdown);
+const safeHtml = DOMPurify.sanitize(html);
+const pdf = await fastify.xPDF.generateFromMarkdown(safeHtml);
+```
+
+---
+
+### 3. Resource Consumption Protection
+
+**Risk**: Unbounded PDF operations could cause DoS or resource exhaustion.
+
+**Scenarios**:
+- Generating many large PDFs concurrently
+- Processing extremely large HTML documents
+- Merging thousands of PDFs
+- Exposed via HTTP without rate limiting
+
+**Mitigation**:
+
+#### A. Implement Concurrency Limits
+```javascript
+import pQueue from 'p-queue';
+
+const pdfQueue = new pQueue({ concurrency: 5, interval: 1000, intervalCap: 50 });
+
+// Wrapper
+const generatePdfLimited = (html, options) =>
+  pdfQueue.add(() => fastify.xPDF.generateFromHtml(html, options));
+
+const pdf = await generatePdfLimited('<h1>Test</h1>');
+```
+
+#### B. Set Timeouts
+```javascript
+// Add to xPDF configuration
+await fastify.register(xPDF, {
+  // Default timeouts are already configured (30s)
+  // You can control them via options
+});
+
+// Or per-operation
+const timeout = new Promise((_, reject) =>
+  setTimeout(() => reject(new Error('PDF timeout')), 60000)
+);
+
+Promise.race([
+  fastify.xPDF.generateFromHtml(html),
+  timeout
+]);
+```
+
+#### C. Rate Limit at HTTP Level
+```javascript
+import rateLimit from '@fastify/rate-limit';
+
+await fastify.register(rateLimit, {
+  max: 100,
+  timeWindow: '15 minutes',
+});
+
+fastify.post('/pdf/generate', async (request, reply) => {
+  const pdf = await fastify.xPDF.generateFromHtml(request.body.html);
+  return { url: pdf.url };
+});
+```
+
+#### D. Monitor Resource Usage
+```javascript
+import os from 'os';
+
+fastify.addHook('onRequest', async (request) => {
+  const memUsage = process.memoryUsage();
+  if (memUsage.heapUsed > 1024 * 1024 * 1024) { // 1GB
+    throw new Error('Server overloaded - please try again later');
+  }
+});
+```
+
+**Runtime Configuration**:
+```bash
+# Limit Node.js heap size
+NODE_OPTIONS=--max-old-space-size=2048 npm start
+
+# Use cgroup limits in Docker
+docker run --memory="2g" --cpus="2" my-app
+```
+
+---
+
+### 4. xStorage Credential Security
+
+**Risk**: S3 credentials stored insecurely
+
+**Safe Practices**:
+```javascript
+// ✅ Use environment variables
+await fastify.register(xStorage, {
+  accessKeyId: process.env.AWS_ACCESS_KEY_ID,
+  secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY,
+});
+
+// ✅ Use IAM roles in AWS/EC2
+// ✅ Use STS temporary credentials
+// ✅ Rotate credentials regularly
+
+// ❌ Never hardcode credentials
+// ❌ Never commit credentials to git
+// ❌ Never log credentials
+```
+
+**xStorage Settings**:
+```javascript
+await fastify.register(xStorage, {
+  // Default ACL: 'private' (secure by default)
+  // Only make specific files public with signed URLs
+  // Never use 'public-read' for sensitive PDFs
+});
+```
+
+---
+
+### 5. HTTP Endpoint Security
+
+**Example Server**:
+```javascript
+import Fastify from 'fastify';
+import rateLimit from '@fastify/rate-limit';
+import helmet from '@fastify/helmet';
+import xPDF from '@xenterprises/fastify-xpdf';
+
+const fastify = Fastify();
+
+// Security headers
+await fastify.register(helmet);
+
+// Rate limiting
+await fastify.register(rateLimit, {
+  max: 100,
+  timeWindow: '15 minutes',
+});
+
+// Register xPDF
+await fastify.register(xPDF, {
+  useStorage: true,
+  defaultFolder: 'pdfs',
+});
+
+// Input validation
+fastify.post('/pdf/generate', async (request, reply) => {
+  // 1. Validate content length
+  const MAX_SIZE = 1024 * 1024; // 1MB
+  if (request.rawBody.length > MAX_SIZE) {
+    throw new Error('Content too large');
+  }
+
+  // 2. Validate format
+  const { html } = request.body;
+  if (typeof html !== 'string' || !html.trim()) {
+    throw new Error('Invalid HTML');
+  }
+
+  // 3. Sanitize if needed
+  const safeHtml = DOMPurify.sanitize(html);
+
+  // 4. Generate PDF with timeout
+  const timeout = new Promise((_, r) =>
+    setTimeout(() => r(new Error('Timeout')), 30000)
+  );
+
+  const pdf = await Promise.race([
+    fastify.xPDF.generateFromHtml(safeHtml),
+    timeout
+  ]);
+
+  return { url: pdf.url };
+});
+
+await fastify.listen({ port: 3000, host: '127.0.0.1' });
+```
+
+---
+
+### 6. Error Handling
+
+**Risk**: Errors could expose internal information
+
+**Best Practice**:
+```javascript
+// ✅ Log full errors internally
+fastify.setErrorHandler((error, request, reply) => {
+  fastify.log.error(error); // Full error logged
+
+  // Return generic error to client
+  reply.status(500).send({
+    error: 'PDF generation failed',
+    code: 'PDF_ERROR',
+    // Don't expose internal details
+  });
+});
+
+// ❌ Don't expose internal errors
+// reply.send({ error: error.message }); // Bad!
+```
+
+---
+
+## Dependency Security
+
+### Regular Updates
+```bash
+# Check for vulnerabilities
+npm audit
+
+# Update to latest secure versions
+npm audit fix
+
+# Subscribe to security updates
+npm audit --audit-level=moderate
+```
+
+### Key Dependencies
+- **puppeteer**: Keep updated for browser security patches
+- **marked**: Check for XSS vulnerabilities
+- **pdf-lib**: Pure JavaScript - no native code risks
+
+---
+
+## Compliance & Standards
+
+### PDF Standards
+- xPDF generates **PDF 1.4** compatible files
+- No encryption by default (passwords not supported in v1.0)
+- No digital signatures (planned for v1.2)
+
+### Data Privacy
+If using xStorage:
+- Configure encryption at rest (S3 SSE)
+- Use HTTPS for all transfers
+- Enable bucket logging
+- Set bucket policies to restrict access
+
+```javascript
+// Example secure xStorage config
+await fastify.register(xStorage, {
+  endpoint: process.env.S3_ENDPOINT,
+  region: process.env.S3_REGION,
+  accessKeyId: process.env.AWS_ACCESS_KEY_ID,
+  secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY,
+  bucket: process.env.S3_BUCKET,
+  publicUrl: process.env.S3_PUBLIC_URL,
+
+  // Use only when absolutely necessary
+  defaultAcl: 'private', // Secure by default
+});
+```
+
+---
+
+## Reporting Security Issues
+
+**Please do not open public GitHub/GitLab issues for security vulnerabilities.**
+
+Email security concerns to: [contact info when available]
+
+Include:
+- Description of vulnerability
+- Steps to reproduce
+- Potential impact
+- Suggested fix (if any)
+
+**Response Time**: We aim to respond within 48 hours and release patches within 2 weeks.
+
+---
+
+## Security Checklist for Production
+
+- [ ] Running in Docker or VM with resource limits
+- [ ] Using strong authentication for xStorage
+- [ ] Rate limiting enabled on HTTP endpoints
+- [ ] Input validation and sanitization in place
+- [ ] Error handling doesn't expose details
+- [ ] Monitoring and logging configured
+- [ ] Security headers enabled (@fastify/helmet)
+- [ ] Dependencies regularly updated
+- [ ] Credentials in environment variables
+- [ ] Access logs enabled
+- [ ] Backup strategy for stored PDFs
+- [ ] HTTPS enforced for all endpoints
+
+---
+
+## Additional Resources
+
+- [OWASP Top 10](https://owasp.org/www-project-top-ten/)
+- [Node.js Security Best Practices](https://nodejs.org/en/docs/guides/security/)
+- [Fastify Security](https://www.fastify.io/docs/latest/Guides/Security/)
+- [Puppeteer Security](https://github.com/puppeteer/puppeteer/blob/main/docs/api.md)
+
+---
+
+## Version History
+
+| Version | Date | Security Updates |
+|---------|------|------------------|
+| 1.0.0 | 2024-12-29 | Initial release |
+
+---
+
+**Last Updated**: 2024-12-29
+**Maintained By**: Tim Mushen

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@xenterprises/fastify-xpdf",
+  "type": "module",
+  "version": "1.0.0",
+  "description": "Fastify plugin for PDF generation and manipulation. Convert HTML/Markdown to PDF, fill forms, and merge PDFs.",
+  "main": "src/index.js",
+  "exports": {
+    ".": "./src/index.js",
+    "./helpers": "./src/utils/helpers.js"
+  },
+  "scripts": {
+    "start": "fastify start -l info server/app.js",
+    "dev": "fastify start -w -l info -P server/app.js",
+    "test": "node --test test/xPDF.test.js"
+  },
+  "keywords": [
+    "fastify",
+    "pdf",
+    "puppeteer",
+    "html-to-pdf",
+    "markdown-to-pdf",
+    "pdf-forms",
+    "pdf-merge",
+    "pdf-generation"
+  ],
+  "author": "Tim Mushen",
+  "license": "ISC",
+  "engines": {
+    "node": ">=20.0.0",
+    "npm": ">=10.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://gitlab.com/x-enterprises/fastify-plugins/fastify-x-pdf"
+  },
+  "bugs": {
+    "url": "https://gitlab.com/x-enterprises/fastify-plugins/fastify-x-pdf/-/issues"
+  },
+  "homepage": "https://gitlab.com/x-enterprises/fastify-plugins/fastify-x-pdf#readme",
+  "dependencies": {
+    "fastify-plugin": "^5.0.0",
+    "marked": "^15.0.0",
+    "pdf-lib": "^1.17.1",
+    "puppeteer": "^23.0.0"
+  },
+  "devDependencies": {
+    "fastify": "^5.1.0"
+  },
+  "peerDependencies": {
+    "@xenterprises/fastify-xstorage": "^1.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@xenterprises/fastify-xstorage": {
+      "optional": true
+    }
+  }
+}

package/server/app.js

@@ -0,0 +1,151 @@
+// server/app.js
+import Fastify from "fastify";
+import xPDF from "../src/xPDF.js";
+
+const fastify = Fastify({
+  logger: true,
+});
+
+// xPDF is a library of methods, not a server with routes
+// The routes below are EXAMPLES of how to use the fastify.xPDF methods
+// You can implement your own routes or use xPDF methods directly in your application
+
+// Register xPDF
+await fastify.register(xPDF, {
+  headless: true,
+  useStorage: false,
+  defaultFolder: "pdfs",
+  format: "A4",
+  printBackground: true,
+  margin: {
+    top: "1cm",
+    right: "1cm",
+    bottom: "1cm",
+    left: "1cm",
+  },
+});
+
+// Example: HTML to PDF
+fastify.post("/pdf/from-html", async (request, reply) => {
+  const { html, filename = "document.pdf" } = request.body;
+
+  if (!html) {
+    return reply.code(400).send({ error: "HTML content required" });
+  }
+
+  const result = await fastify.xPDF.generateFromHtml(html, {
+    filename,
+    saveToStorage: false,
+  });
+
+  return {
+    success: true,
+    filename: result.filename,
+    size: result.size,
+  };
+});
+
+// Example: Markdown to PDF
+fastify.post("/pdf/from-markdown", async (request, reply) => {
+  const { markdown, filename = "document.pdf" } = request.body;
+
+  if (!markdown) {
+    return reply.code(400).send({ error: "Markdown content required" });
+  }
+
+  const result = await fastify.xPDF.generateFromMarkdown(markdown, {
+    filename,
+    saveToStorage: false,
+  });
+
+  return {
+    success: true,
+    filename: result.filename,
+    size: result.size,
+  };
+});
+
+// Example: Fill PDF form
+fastify.post("/pdf/fill-form", async (request, reply) => {
+  const { pdfBase64, fieldValues = {}, filename = "filled-form.pdf" } = request.body;
+
+  if (!pdfBase64) {
+    return reply.code(400).send({ error: "PDF (base64) required" });
+  }
+
+  // Convert base64 to buffer
+  const pdfBuffer = Buffer.from(pdfBase64, "base64");
+
+  const result = await fastify.xPDF.fillForm(pdfBuffer, fieldValues, {
+    flatten: true,
+    filename,
+    saveToStorage: false,
+  });
+
+  return {
+    success: true,
+    filename: result.filename,
+    size: result.size,
+  };
+});
+
+// Example: List PDF form fields
+fastify.post("/pdf/list-fields", async (request, reply) => {
+  const { pdfBase64 } = request.body;
+
+  if (!pdfBase64) {
+    return reply.code(400).send({ error: "PDF (base64) required" });
+  }
+
+  // Convert base64 to buffer
+  const pdfBuffer = Buffer.from(pdfBase64, "base64");
+
+  const fields = await fastify.xPDF.listFormFields(pdfBuffer);
+
+  return {
+    success: true,
+    fields,
+    count: fields.length,
+  };
+});
+
+// Example: Merge PDFs
+fastify.post("/pdf/merge", async (request, reply) => {
+  const { pdfsBase64 = [], filename = "merged.pdf" } = request.body;
+
+  if (!Array.isArray(pdfsBase64) || pdfsBase64.length === 0) {
+    return reply.code(400).send({ error: "Array of PDFs (base64) required" });
+  }
+
+  // Convert base64 strings to buffers
+  const buffers = pdfsBase64.map((base64) => Buffer.from(base64, "base64"));
+
+  const result = await fastify.xPDF.mergePDFs(buffers, {
+    filename,
+    saveToStorage: false,
+  });
+
+  return {
+    success: true,
+    filename: result.filename,
+    size: result.size,
+    pageCount: result.pageCount,
+  };
+});
+
+// Health check
+fastify.get("/health", async () => {
+  return { status: "ok", timestamp: new Date().toISOString() };
+});
+
+// Start server
+const start = async () => {
+  try {
+    await fastify.listen({ port: process.env.PORT || 3000, host: "0.0.0.0" });
+  } catch (err) {
+    fastify.log.error(err);
+    process.exit(1);
+  }
+};
+
+start();

package/src/index.js

@@ -0,0 +1,7 @@
+/**
+ * Main exports for xPDF plugin
+ */
+
+export { default } from "./xPDF.js";
+export { default as xPDF } from "./xPDF.js";
+export * as helpers from "./utils/helpers.js";