polotno-node 3.14.0 → 3.15.0

package/lib/ssrf-guard.js

@@ -1,132 +1,20 @@
 import dns from 'dns/promises';
-import net from 'net';
-import { polotnoError } from './errors.js';
-// Cloud metadata endpoints — AWS/GCP/Azure (169.254.169.254), ECS task role
-// (169.254.170.2), and the IPv6 form. Never a legitimate render target.
-const METADATA_IPS = new Set([
-    '169.254.169.254',
-    '169.254.170.2',
-    'fd00:ec2::254',
-]);
-// Metadata hostnames (GCP) — caught by name even where they don't resolve.
-const METADATA_HOSTS = new Set(['metadata.google.internal', 'metadata.goog']);
-// A real metadata A-record resolves in ms; a slow resolver fails open promptly.
-const DNS_TIMEOUT_MS = 1500;
-// Resolve to addresses; [] on error/timeout (fail open). Never rejects.
-const resolveHost = async (host) => {
-    let timer;
-    try {
-        const addresses = await Promise.race([
-            dns.lookup(host, { all: true }),
-            new Promise((_, reject) => {
-                timer = setTimeout(() => reject(new Error('dns-timeout')), DNS_TIMEOUT_MS);
-            }),
-        ]);
-        return addresses.map((a) => a.address);
-    }
-    catch {
-        return [];
-    }
-    finally {
-        clearTimeout(timer);
-    }
-};
-const blocked = (url, why) => {
-    const err = polotnoError('FETCH_FAILED', `Blocked request to ${url}: ${why} (SSRF protection). ` +
-        `Pass a fetchGuard to override, or blockPrivateNetwork:false to relax.`, { url });
-    // A deterministic policy rejection — the download loop must not retry it.
-    err.ssrfBlocked = true;
-    return err;
-};
-const ipv4IsPrivate = (ip) => {
-    const [a, b] = ip.split('.').map(Number);
-    if (a === 127)
-        return true; // loopback 127.0.0.0/8
-    if (a === 10)
-        return true; // 10.0.0.0/8
-    if (a === 172 && b >= 16 && b <= 31)
-        return true; // 172.16.0.0/12
-    if (a === 192 && b === 168)
-        return true; // 192.168.0.0/16
-    if (a === 169 && b === 254)
-        return true; // link-local 169.254.0.0/16
-    if (a === 100 && b >= 64 && b <= 127)
-        return true; // CGNAT 100.64.0.0/10
-    if (a === 0)
-        return true; // 0.0.0.0/8
-    return false;
-};
-const ipv6IsPrivate = (ip) => {
-    const v = ip.toLowerCase();
-    if (v === '::1' || v === '::')
-        return true; // loopback / unspecified
-    if (v.startsWith('fe80'))
-        return true; // link-local
-    if (v.startsWith('fc') || v.startsWith('fd'))
-        return true; // unique local
-    return false;
-};
-// Unwrap an IPv4-mapped IPv6 address to its dotted-quad form, or null. Handles
-// both the dotted (`::ffff:169.254.169.254`) and hex (`::ffff:a9fe:a9fe`)
-// spellings — Node's `URL` normalizes the former into the latter, so a guard
-// that only knew the dotted form could be bypassed with a bracketed literal.
-const unwrapMappedV4 = (addr) => {
-    const dotted = addr.match(/^::ffff:(\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3})$/);
-    if (dotted)
-        return dotted[1];
-    const hex = addr.match(/^::ffff:([0-9a-f]{1,4}):([0-9a-f]{1,4})$/);
-    if (hex) {
-        const hi = parseInt(hex[1], 16);
-        const lo = parseInt(hex[2], 16);
-        return `${(hi >> 8) & 255}.${hi & 255}.${(lo >> 8) & 255}.${lo & 255}`;
-    }
-    return null;
-};
-// Returns a reason string if the address must be blocked, else null.
-const addressBlockReason = (ip, blockPrivate) => {
-    let addr = ip.toLowerCase();
-    addr = unwrapMappedV4(addr) ?? addr;
-    if (METADATA_IPS.has(addr))
-        return 'cloud-metadata endpoint';
-    if (!blockPrivate)
-        return null;
-    if (net.isIPv4(addr) && ipv4IsPrivate(addr))
-        return 'private/loopback address';
-    if (net.isIPv6(addr) && ipv6IsPrivate(addr))
-        return 'private/loopback address';
-    return null;
-};
+import { fetchWithRetry } from '@polotno/core/retry';
+import { assertUrlAllowed as assertWithResolver, urlValidator, } from '@polotno/core/ssrf-guard';
+const resolveHost = (host) => dns.lookup(host, { all: true }).then((all) => all.map((a) => a.address));
 /**
- * Throw a branded FETCH_FAILED error if `urlString` must not be fetched under
- * `policy`. Resolves DNS for hostnames and checks every returned address.
- * No-throw = allowed.
+ * Throw `FETCH_FAILED` (marked `ssrfBlocked: true`) if `url` must not be
+ * fetched under `policy`. Hostnames are resolved and every address checked.
  */
-export const assertUrlAllowed = async (urlString, policy = {}) => {
-    if (policy.fetchGuard) {
-        const ok = await policy.fetchGuard(urlString);
-        if (!ok)
-            throw blocked(urlString, 'rejected by fetchGuard');
-        return;
-    }
-    let parsed;
-    try {
-        parsed = new URL(urlString);
-    }
-    catch {
-        // Malformed URL — let the caller's fetch surface the real error.
-        return;
-    }
-    if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:')
-        return;
-    // Strip IPv6 brackets: new URL('http://[::1]/').hostname === '[::1]'.
-    const host = parsed.hostname.replace(/^\[|\]$/g, '').toLowerCase();
-    if (METADATA_HOSTS.has(host))
-        throw blocked(urlString, 'metadata hostname');
-    const addresses = net.isIP(host) ? [host] : await resolveHost(host);
-    const blockPrivate = !!policy.blockPrivateNetwork;
-    for (const ip of addresses) {
-        const reason = addressBlockReason(ip, blockPrivate);
-        if (reason)
-            throw blocked(urlString, reason);
-    }
-};
+export const assertUrlAllowed = (url, policy = {}) => assertWithResolver(url, policy, resolveHost);
+/**
+ * One `fetch` with `assertUrlAllowed` applied to the URL and every redirect
+ * hop (at most 5). Resolves with an ok response; a blocked URL, an HTTP error
+ * or a timeout rejects with `FETCH_FAILED`. `init.timeout` bounds the wait for
+ * the response headers (default 30 s), not the body.
+ */
+export const guardedFetch = (url, policy = {}, init = {}) => fetchWithRetry(url, {
+    ...init,
+    retries: 1,
+    validateUrl: urlValidator(policy, resolveHost),
+});

package/lib/types.d.ts

@@ -29,6 +29,34 @@ export interface RenderOptions {
     onProgress?: (progress: number) => void;
     /** Path to save CPU profile (.cpuprofile) - loadable in Chrome DevTools */
     profilePath?: string;
+    /**
+     * SSRF hardening for every URL the render requests: each http(s) request
+     * the render page sends (images, SVGs, fonts, media, redirect hops) and the
+     * video export's server-side media downloads. Cloud-metadata endpoints (e.g.
+     * 169.254.169.254) are blocked whatever this is set to — whether named by
+     * literal IP, a known metadata hostname, or a hostname that resolves to one
+     * (best-effort; a resolve-then-fetch guard leaves a small DNS-rebinding
+     * window). Set this to ALSO reject loopback, link-local and private (RFC1918
+     * / ULA) addresses — enable it when the design JSON is untrusted and the
+     * renderer has no legitimate reason to reach internal hosts. Default:
+     * `false` (localhost and private hosts allowed).
+     */
+    blockPrivateNetwork?: boolean;
+    /**
+     * Full override for the SSRF check: return `false` to reject a URL. When
+     * provided it is the sole authority — the built-in IP checks are skipped.
+     * It sees every http(s) URL the render requests, redirect hops included,
+     * except the client's own services: the Polotno license check and Google
+     * Fonts.
+     */
+    fetchGuard?: (url: string) => boolean | Promise<boolean>;
+    /**
+     * Serve `file:` sources named in the design (default: `true`). Set `false`
+     * when the design JSON is untrusted: a design with any `file:` source is
+     * then rejected with `DESIGN_INVALID` before rendering. Media that a video
+     * export downloads itself is still served.
+     */
+    allowLocalFiles?: boolean;
 }
 export interface PDFRenderOptions extends RenderOptions {
     dpi?: number;
@@ -67,26 +95,9 @@ export interface VideoRenderOptions extends RenderOptions {
      * pre-download remote video/audio sources into a temp folder and serve them to the
      * renderer from there, for more reliable and faster loading. Set `skipDownloads: true`
      * to disable that and let the browser load the original URLs itself. Local (`file:`)
-     * sources are always served, whatever this is set to.
+     * sources are served whatever this is set to; `allowLocalFiles` controls them.
      */
     skipDownloads?: boolean;
-    /**
-     * SSRF hardening for the server-side media downloads above. Cloud-metadata
-     * endpoints (e.g. 169.254.169.254) are blocked by default — whether named by
-     * literal IP, a known metadata hostname, or a hostname that resolves to one
-     * (best-effort; a resolve-then-fetch guard leaves a small DNS-rebinding
-     * window). Set this to ALSO reject loopback, link-local and private (RFC1918 /
-     * ULA) addresses — enable it when the design JSON is untrusted and the
-     * renderer has no legitimate reason to reach internal hosts. Default: `false`
-     * (localhost and private hosts allowed).
-     */
-    blockPrivateNetwork?: boolean;
-    /**
-     * Full override for the download SSRF check: return `false` to reject a URL.
-     * When provided it is the sole authority — the built-in IP checks are skipped.
-     * Redirects are validated per-hop with the same rule.
-     */
-    fetchGuard?: (url: string) => boolean | Promise<boolean>;
 }
 export type RenderJSON = DesignInput;
 export interface BrowserOptions {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "polotno-node",
-  "version": "3.14.0",
+  "version": "3.15.0",
   "description": "Polotno workflow from NodeJS",
   "license": "SEE LICENSE IN LICENSE.md",
   "type": "module",
@@ -21,6 +21,11 @@
       "types": "./lib/errors.d.ts",
       "import": "./lib/errors.js",
       "default": "./lib/errors.js"
+    },
+    "./ssrf-guard": {
+      "types": "./lib/ssrf-guard.d.ts",
+      "import": "./lib/ssrf-guard.js",
+      "default": "./lib/ssrf-guard.js"
     }
   },
   "files": [
@@ -35,9 +40,8 @@
     "@polotno/video-export"
   ],
   "devDependencies": {
-    "@polotno/core": "0.18.0",
     "@polotno/design-fixtures": "0.0.0",
-    "@polotno/video-export": "0.5.0",
+    "@polotno/video-export": "0.5.1",
     "@types/node": "^26.6.5",
     "dotenv": "^18.0.8",
     "jspdf": "^4.2.1",
@@ -45,7 +49,7 @@
     "mediabunny": "^1.61.6",
     "pixelmatch": "^7.2.0",
     "pngjs": "^7.0.0",
-    "polotno": "4.17.0",
+    "polotno": "4.18.0",
     "react": "^19.3.1",
     "react-dom": "^19.3.1",
     "tmp": "^0.2.7",
@@ -62,7 +66,8 @@
   },
   "author": "Anton Lavrenov",
   "dependencies": {
-    "@polotno/schema": "0.9.0",
+    "@polotno/core": "0.19.0",
+    "@polotno/schema": "0.9.1",
     "@sparticuz/chromium": "^153.0.0",
     "puppeteer": "25.14.0",
     "puppeteer-core": "25.14.0"
@@ -74,7 +79,7 @@
   "readmeFilename": "README.md",
   "scripts": {
     "build": "rm -rf ./lib ./dist && tsc -p tsconfig.json && vite build ./client/ --base=./ --outDir ../dist --emptyOutDir --logLevel error",
-    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "typecheck": "node ../../scripts/typecheck.mjs --noEmit -p tsconfig.json",
     "test": "if [ -z \"$TURBO_HASH\" ]; then pnpm exec turbo run build --filter=polotno-node --output-logs=new-only --log-order=stream; fi && vitest run test/unit test/static",
     "test:update-goldens": "rm -f test/static/goldens/*.png test/static/goldens/matrix/*.png && pnpm run test",
     "test:video": "if [ -z \"$TURBO_HASH\" ]; then pnpm exec turbo run build --filter=polotno-node --output-logs=new-only; fi && vitest run test/video/video.test.mjs",