feat: Replace image-to-base64 with axios for robust timeout and size controls

- Replace image-to-base64 library with axios for better control over HTTP requests
- Add configurable timeout (default 5s) to prevent hung image downloads
- Add maximum image size limits (default 10MB) to prevent memory issues
- Implement exponential backoff on timeouts for retry attempts
- Add proper error handling for HTTP status codes and network errors
- Update TypeScript definitions and documentation

Security improvements:
- Prevents DoS attacks from slow/unresponsive image servers
- Bounded resource usage with size and timeout limits
- Better error categorization (timeout vs network vs HTTP errors)

DRY improvements:
- Extracted downloadImageToBase64 to src/utils/image.js
- Eliminated duplicate function definitions between helper files
- Added input validation for timeout/size parameters
- Enhanced error messages with structured logging

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>

Author: nicolasiscoding

README.md

@@ -97,7 +97,9 @@ async function withImageOptions() {
   const docx = await HtmlToDocx(htmlWithImages, null, {
     imageProcessing: {
       maxRetries: 3,          // Retry failed image downloads up to 3 times
-      verboseLogging: true    // Enable detailed logging for debugging
+      verboseLogging: true,   // Enable detailed logging for debugging
+      downloadTimeout: 10000, // 10 second timeout per download attempt
+      maxImageSize: 5242880   // 5MB max image size
     }
   });
 }
@@ -225,6 +227,8 @@ full fledged examples can be found under `example/`
   - `imageProcessing` <?[Object]>
     - `maxRetries` <?[Number]> maximum number of retry attempts for failed image downloads. Defaults to `2`.
     - `verboseLogging` <?[Boolean]> flag to enable detailed logging of image processing operations. Defaults to `false`.
+    - `downloadTimeout` <?[Number]> timeout in milliseconds for each image download attempt. Defaults to `5000` (5 seconds).
+    - `maxImageSize` <?[Number]> maximum allowed image size in bytes. Defaults to `10485760` (10MB).
 - `footerHTMLString` <[String]> clean html string equivalent of footer. Defaults to `<p></p>` if footer flag is `true`.
 
 ### Returns

index.d.ts

@@ -73,6 +73,8 @@ declare namespace HTMLtoDOCX {
         imageProcessing?: {
             maxRetries?: number;
             verboseLogging?: boolean;
+            downloadTimeout?: number;
+            maxImageSize?: number;
         };
     }
 }

package-lock.json

@@ -98,7 +98,7 @@
     "juralio-james",
     "robinminso",
     "shareefalis",
-    "adymo", 
+    "adymo",
     "Srajan-Sanjay-Saxena"
   ],
   "license": "MIT",
@@ -131,12 +131,12 @@
     "typescript": "^5.8.3"
   },
   "dependencies": {
+    "axios": "^1.12.2",
     "color-name": "^1.1.4",
     "html-entities": "^2.3.3",
     "html-minifier-terser": "^7.2.0",
     "html-to-vdom": "^0.7.0",
     "image-size": "^2.0.2",
-    "image-to-base64": "^2.2.0",
     "jszip": "^3.7.1",
     "lodash": "^4.17.21",
     "mime-types": "^2.1.35",

package.json

@@ -85,6 +85,8 @@ const defaultDocumentOptions = {
   imageProcessing: {
     maxRetries: 2,
     verboseLogging: false,
+    downloadTimeout: 5000, // 5 seconds per download attempt
+    maxImageSize: 10485760, // 10MB max per image
   },
 };
 const defaultHTMLString = '<p></p>';

src/constants.js

@@ -8,7 +8,6 @@ import isVText from 'virtual-dom/vnode/is-vtext';
 // eslint-disable-next-line import/no-named-default
 import { default as HTMLToVDOM } from 'html-to-vdom';
 import sizeOf from 'image-size';
-import imageToBase64 from 'image-to-base64';
 
 // FIXME: remove the cyclic dependency
 // eslint-disable-next-line import/no-cycle
@@ -18,7 +17,7 @@ import namespaces from '../namespaces';
 import { imageType, internalRelationship, defaultDocumentOptions } from '../constants';
 import { vNodeHasChildren } from '../utils/vnode';
 import { isValidUrl } from '../utils/url';
-import { getMimeType } from '../utils/image';
+import { getMimeType, downloadImageToBase64 } from '../utils/image';
 
 const convertHTML = HTMLToVDOM({
   VNode,
@@ -73,6 +72,7 @@ const logVerbose = (verboseLogging, message, ...args) => {
   }
 };
 
+
 // eslint-disable-next-line consistent-return, no-shadow
 export const buildImage = async (
   docxDocumentInstance,
@@ -124,7 +124,12 @@ export const buildImage = async (
             `[RETRY] Attempt ${attempt}/${maxRetries} for: ${imageSource}`
           );
 
-          base64String = await imageToBase64(imageSource);
+          // Use configurable timeout, default 5 seconds, with exponential backoff for retries
+          const baseTimeout = Math.max(1000, Math.min(options.downloadTimeout || 5000, 30000)); // 1s-30s range
+          const timeoutMs = baseTimeout * attempt;
+          const maxSizeBytes = Math.max(1024, options.maxImageSize || 10 * 1024 * 1024); // min 1KB
+
+          base64String = await downloadImageToBase64(imageSource, timeoutMs, maxSizeBytes);
           if (base64String) {
             if (attempt > 1) {
               retryStats.successAfterRetry += 1;