polotno-node 3.1.3 → 3.3.0

package/lib/launch-options.d.ts

@@ -0,0 +1,31 @@
+import type { BrowserOptions } from './types.js';
+export declare const args: string[];
+/** The one platform `@sparticuz/chromium` builds its binary for. */
+export declare const BUNDLED_CHROMIUM_PLATFORM = "linux";
+/**
+ * Do we launch the chromium binary that `@sparticuz/chromium` ships?
+ *
+ * Only on its platform, and only when the caller has not named a browser of
+ * their own. macOS and Windows run puppeteer's bundled Chromium; a caller who
+ * passes `executablePath` — a container's google-chrome-stable, playwright's
+ * build — runs that.
+ */
+export declare function usesBundledChromium(options?: BrowserOptions, platform?: string): boolean;
+/**
+ * The flags to launch with. `@sparticuz/chromium`'s args are tuned for the
+ * binary it ships (`--single-process`, `--in-process-gpu`, swiftshader ANGLE)
+ * and belong to it alone: given to a system Chrome they range from wasteful to
+ * fatal — `--single-process` in particular can leave Chrome dying mid-handshake,
+ * which surfaces only as "Protocol error (Target.setDiscoverTargets): Target
+ * closed". So they travel with the binary. Our own args, which keep rendering
+ * identical to the editor's canvas, always apply, and the caller's
+ * `browserArgs` win over both.
+ */
+export declare function resolveBrowserArgs(options?: BrowserOptions, platform?: string): string[];
+/**
+ * The browser to launch: the caller's, else the bundled chromium where we use
+ * it, else puppeteer's own. Resolving the bundled one is not free — it inflates
+ * chromium, the fonts and swiftshader into /tmp — so we only ask for it when it
+ * is the one we launch.
+ */
+export declare function resolveExecutablePath(options?: BrowserOptions, platform?: string): Promise<string | undefined>;

package/lib/launch-options.js

@@ -0,0 +1,124 @@
+import os from 'os';
+import sparticuz from '@sparticuz/chromium';
+// TODO: that is a weird hack, but it works
+const chrome = sparticuz.default || sparticuz;
+export const args = [
+    'about:blank',
+    '--disable-web-security',
+    '--allow-file-access-from-files',
+    '--allow-pre-commit-input',
+    '--autoplay-policy=user-gesture-required',
+    '--disable-background-networking',
+    '--disable-background-timer-throttling',
+    '--disable-backgrounding-occluded-windows',
+    '--disable-breakpad',
+    '--disable-component-extensions-with-background-pages',
+    '--disable-client-side-phishing-detection',
+    '--disable-component-update',
+    '--disable-default-apps',
+    '--disable-dev-shm-usage',
+    '--proxy-server=direct://',
+    '--proxy-bypass-list=*',
+    '--disable-domain-reliability',
+    '--disable-features=AudioServiceOutOfProcess,IsolateOrigins,site-per-process,Translate,BackForwardCache,AvoidUnnecessaryBeforeUnloadCheckSync,IntensiveWakeUpThrottling',
+    '--disable-extensions',
+    '--disable-hang-monitor',
+    '--disable-ipc-flooding-protection',
+    '--disable-notifications',
+    '--disable-offer-store-unmasked-wallet-cards',
+    '--disable-popup-blocking',
+    '--disable-print-preview',
+    '--disable-site-isolation-trials',
+    '--disable-prompt-on-repost',
+    '--disable-renderer-backgrounding',
+    '--disable-setuid-sandbox',
+    '--disable-speech-api',
+    '--disable-sync',
+    // Use srgb for identical output across Linux/macOS/Windows and to match how CSS colors/images are defined/assumed on the web.
+    '--force-color-profile=srgb',
+    '--hide-scrollbars',
+    '--metrics-recording-only',
+    '--mute-audio',
+    '--no-default-browser-check',
+    '--no-first-run',
+    '--enable-automation',
+    '--no-pings',
+    '--no-sandbox',
+    '--no-zygote',
+    '--password-store=basic',
+    '--allow-running-insecure-content',
+    // Disable accessibility features to reduce resource usage and improve performance.
+    '--disable-renderer-accessibility',
+    // stable locale → font fallback/hyphenation
+    '--lang=en-US',
+    // this line  breaks the rendering on most of OS
+    // it doesn't allow creating of pages
+    //'--use-gl=swiftshader',
+    '--disable-gpu',
+    '--use-mock-keychain',
+    '--enable-blink-features=IdleDetection',
+    '--intensive-wake-up-throttling-policy=0',
+    '--font-render-hinting=none',
+    '--ignore-gpu-blocklist',
+    // don't use this flag, because it makes renderign less accurate
+    // see https://community.polotno.com/c/ask/the-ability-to-exclude-args-from-minimal_args-in-polotno-node
+    // '--disable-font-subpixel-positioning',
+    '--text-rendering=geometricprecision',
+];
+/**
+ * Merge browser argument arrays, deduping by flag name (the part before `=`).
+ * Later arrays take precedence on conflict.
+ */
+function mergeArgs(...argArrays) {
+    const argMap = new Map();
+    for (const argArray of argArrays) {
+        for (const arg of argArray) {
+            const flagMatch = arg.match(/^(--[^=]+)/);
+            const flagName = flagMatch ? flagMatch[1] : arg;
+            argMap.set(flagName, arg);
+        }
+    }
+    return Array.from(argMap.values());
+}
+/** The one platform `@sparticuz/chromium` builds its binary for. */
+export const BUNDLED_CHROMIUM_PLATFORM = 'linux';
+/**
+ * Do we launch the chromium binary that `@sparticuz/chromium` ships?
+ *
+ * Only on its platform, and only when the caller has not named a browser of
+ * their own. macOS and Windows run puppeteer's bundled Chromium; a caller who
+ * passes `executablePath` — a container's google-chrome-stable, playwright's
+ * build — runs that.
+ */
+export function usesBundledChromium(options = {}, platform = os.platform()) {
+    return platform === BUNDLED_CHROMIUM_PLATFORM && !options.executablePath;
+}
+/**
+ * The flags to launch with. `@sparticuz/chromium`'s args are tuned for the
+ * binary it ships (`--single-process`, `--in-process-gpu`, swiftshader ANGLE)
+ * and belong to it alone: given to a system Chrome they range from wasteful to
+ * fatal — `--single-process` in particular can leave Chrome dying mid-handshake,
+ * which surfaces only as "Protocol error (Target.setDiscoverTargets): Target
+ * closed". So they travel with the binary. Our own args, which keep rendering
+ * identical to the editor's canvas, always apply, and the caller's
+ * `browserArgs` win over both.
+ */
+export function resolveBrowserArgs(options = {}, platform = os.platform()) {
+    const { browserArgs = [] } = options;
+    return usesBundledChromium(options, platform)
+        ? mergeArgs(chrome.args, args, browserArgs)
+        : mergeArgs(args, browserArgs);
+}
+/**
+ * The browser to launch: the caller's, else the bundled chromium where we use
+ * it, else puppeteer's own. Resolving the bundled one is not free — it inflates
+ * chromium, the fonts and swiftshader into /tmp — so we only ask for it when it
+ * is the one we launch.
+ */
+export async function resolveExecutablePath(options = {}, platform = os.platform()) {
+    if (options.executablePath)
+        return options.executablePath;
+    return usesBundledChromium(options, platform)
+        ? await chrome.executablePath()
+        : undefined;
+}

package/lib/ssrf-guard.d.ts

@@ -0,0 +1,15 @@
+export interface FetchPolicy {
+    /** Also block loopback, link-local and private (RFC1918 / ULA) addresses. */
+    blockPrivateNetwork?: boolean;
+    /**
+     * Full override. Return `false` to reject the URL. When provided, the
+     * built-in IP checks are skipped and this is the sole authority.
+     */
+    fetchGuard?: (url: string) => boolean | Promise<boolean>;
+}
+/**
+ * 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.
+ */
+export declare const assertUrlAllowed: (urlString: string, policy?: FetchPolicy) => Promise<void>;

package/lib/ssrf-guard.js

@@ -0,0 +1,132 @@
+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;
+};
+/**
+ * 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.
+ */
+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);
+    }
+};

package/lib/types.d.ts

@@ -37,11 +37,28 @@ export interface VideoRenderOptions extends RenderOptions {
      * URLs for more reliable and faster loading. Set `skipDownloads: true` to disable that.
      */
     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 {
     browserArgs?: string[];
-    headless?: 'new' | boolean;
+    headless?: boolean | 'shell';
     protocolTimeout?: number;
     ignoreHTTPSErrors?: boolean;
     executablePath?: string;
@@ -52,10 +69,22 @@ export interface InstanceOptions {
     useParallelPages?: boolean;
     browserArgs?: string[];
     browser?: Browser;
+    /**
+     * Launch this browser binary instead of the one we would pick — a container's
+     * google-chrome-stable, say. Ignored when you pass your own `browser`.
+     */
+    executablePath?: string;
     /** Intercept every page request (e.g. to block or rewrite asset loads). */
     requestInterceptor?: (request: any) => void;
     /** Cache Google Fonts responses for the process lifetime and serve them to every page (default: true) */
     useFontCache?: boolean;
+    /**
+     * Budget for the initial navigation to the client page, in ms (default:
+     * 120000). Distinct from `protocolTimeout`, which governs CDP calls and not
+     * the navigation lifecycle. Raise it on slow machines; `0` disables it, at
+     * the cost of turning a wedged load into a permanent hang.
+     */
+    navigationTimeout?: number;
 }
 export interface PolotnoInstance {
     close: () => Promise<void>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "polotno-node",
-  "version": "3.1.3",
+  "version": "3.3.0",
   "description": "Polotno workflow from NodeJS",
   "license": "SEE LICENSE IN LICENSE.md",
   "type": "module",
@@ -35,24 +35,24 @@
     "@polotno/video-export"
   ],
   "devDependencies": {
-    "@types/node": "^26.1.1",
-    "mediabunny": "^1.50.8",
-    "axios": "^1.18.1",
+    "@types/node": "^26.1.2",
+    "mediabunny": "^1.52.3",
+    "axios": "^1.19.0",
     "dotenv": "^17.4.2",
     "fluent-ffmpeg": "^2.1.3",
     "jspdf": "^4.2.1",
     "konva": "^10.3.0",
     "pixelmatch": "^7.2.0",
     "pngjs": "^7.0.0",
-    "react": "^19.2.7",
-    "react-dom": "^19.2.7",
+    "react": "^19.2.8",
+    "react-dom": "^19.2.8",
     "tmp": "^0.2.7",
     "typescript": "~6.0.3",
-    "vite": "^8.1.4",
+    "vite": "^8.2.1",
     "vitest": "^4.1.10",
     "web-audio-api": "^1.5.3",
-    "polotno": "4.5.2",
-    "@polotno/video-export": "0.2.1"
+    "polotno": "4.7.0",
+    "@polotno/video-export": "0.2.3"
   },
   "overrides": {
     "@polotno/video-export": {
@@ -63,9 +63,9 @@
   "author": "Anton Lavrenov",
   "dependencies": {
     "@sparticuz/chromium": "^149.0.0",
-    "puppeteer": "25.3.0",
-    "puppeteer-core": "25.3.0",
-    "@polotno/schema": "0.3.0"
+    "puppeteer": "25.5.0",
+    "puppeteer-core": "25.5.0",
+    "@polotno/schema": "0.5.0"
   },
   "bugs": {
     "url": "https://github.com/polotno-project/polotno-node/issues"
@@ -75,9 +75,9 @@
   "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",
-    "test": "pnpm run build && vitest run test/unit test/static/static.test.mjs",
-    "test:video": "pnpm run build && vitest run test/video/video.test.mjs",
-    "test:all": "pnpm run build && vitest run test/unit test/static/static.test.mjs test/video/video.test.mjs",
+    "test": "pnpm exec turbo run build --filter=polotno-node --output-logs=new-only --log-order=stream && vitest run test/unit test/static/static.test.mjs",
+    "test:video": "pnpm exec turbo run build --filter=polotno-node && vitest run test/video/video.test.mjs",
+    "test:all": "pnpm exec turbo run build --filter=polotno-node && vitest run test/unit test/static/static.test.mjs test/video/video.test.mjs",
     "dev": "vite ./client.html"
   }
 }