polotno-node 3.14.0 → 3.15.0

package/README.md

@@ -80,8 +80,10 @@ const instance = await createInstance({
   // for full Chrome. Ignored if you pass `browser`.
   headless: true,
 
-  // useFontCache - cache Google Fonts responses (in memory + on disk in the
-  // OS temp folder, shared across processes) and serve them to every page.
+  // useFontCache - cache Google Fonts responses (in memory + on disk in a
+  // private folder in the OS temp folder, shared across this user's processes)
+  // and serve them to every page. Only https responses from
+  // fonts.googleapis.com and fonts.gstatic.com are cached.
   // Every page starts with an empty HTTP cache, so without it each render
   // re-downloads the same fonts and bursts of parallel renders may get
   // throttled by Google Fonts (fonts time out and text falls back to a
@@ -93,6 +95,9 @@ const instance = await createInstance({
   // - Modify headers like User-Agent to access protected image resources
   // - Add authentication tokens or credentials to requests
   // - Log or monitor network traffic
+  // It runs after polotno-node's own handling: local files and cached fonts
+  // are answered before it, and requests the URL policy blocks never reach it
+  // (see "Restricted hosts" and "Local files").
   requestInterceptor: (request) => {
     const targetUrl = request.url();
     if (/\.(png|jpe?g)(\?|$)/i.test(targetUrl)) {
@@ -321,7 +326,7 @@ Native audio processing and finalization can also take time without intermediate
 Custom clients with older video exporters can report fewer stages.
 
 The inactivity timer runs in Node, so it can report a blocked renderer without another CDP request.
-It cannot fire while Node itself is blocked, including during synchronous media conversion or base64 conversion.
+It cannot fire while Node itself is blocked, for example during base64 conversion.
 An independent parent-process monitor is necessary to detect that condition during the block.
 Existing `protocolTimeout` and navigation timeouts still apply.
 
@@ -360,7 +365,7 @@ By default, when exporting video and **only** when using the default local clien
 - Download all **remote** video elements (`type: 'video'`) and `json.audios` sources into a temporary folder
 - Deduplicate downloads (same URL is downloaded once)
 - Probe downloaded remote videos with `ffprobe`
-- Conditionally normalize incompatible downloaded videos into MP4 with H.264 video, `yuv420p`, and AAC audio for better Chromium render compatibility
+- Conditionally normalize incompatible downloaded videos into MP4 with H.264 video, `yuv420p`, and AAC audio for better Chromium render compatibility. `ffprobe` and `ffmpeg` run as child processes and do not block Node. Each run is stopped at a time limit: a probe after 30 seconds (the video is then used as it is), and a conversion after 10 minutes (the export then fails).
 - Rewrite `src` to a URL that `polotno-node` answers from the temporary folder
 
 For best compatibility, use MP4 with H.264 (`yuv420p`) video and AAC audio.
@@ -381,17 +386,42 @@ A `file:` source anywhere in a design — an image, an SVG, a video, an audio tr
 
 Because the bytes come from Node, a browser running somewhere else (`browser: await puppeteer.connect(...)`, browserless) can render a design that names files on this machine.
 
-### Restricted media hosts
+Local files are served before, and without, your `requestInterceptor`: it never sees these reads, so it cannot block them. If you render designs from users you do not trust, turn local files off:
 
-Server-side downloads block cloud-metadata addresses (e.g. `169.254.169.254`) by default. Normal URLs, `localhost`, and private hosts still work. To restrict further:
+```js
+await instance.jsonToImageBase64(json, { allowLocalFiles: false });
+```
+
+With `allowLocalFiles: false`, a design that names any `file:` source is rejected with a `DESIGN_INVALID` error before rendering. Each `details.errors` entry names the field. The remote media that a video export downloads for itself is still served.
+
+Whatever `allowLocalFiles` is set to, the render page cannot read files directly: a `file:` request from the page outside the client's own folder is refused. A `file:` URL that a script inside `instance.run()` loads itself (not through the design) is refused too: the script gets a `403` whose text explains why, and the refusal is logged with `console.warn`. Put the `file:` URL in the design instead, or read the file in Node and pass its contents in.
+
+### Restricted hosts
+
+Every http(s) request the render makes is checked first: each request the render page sends (images, SVGs, fonts, media, and each redirect hop), and the server-side media downloads of a video export. Cloud-metadata addresses (e.g. `169.254.169.254`) are blocked by default. Normal URLs, `localhost`, and private hosts still work. A blocked asset fails like any asset that does not load (for example `IMAGE_FAILED`, unless `skipImageError` is set). The check runs before your `requestInterceptor`. To restrict further, in any export method:
 
 ```js
-await instance.jsonToVideoFile(json, 'out.mp4', {
+await instance.jsonToImageBase64(json, {
   blockPrivateNetwork: true, // also block loopback / private IPs
   fetchGuard: (url) => isAllowed(url), // custom allow rule (checked per redirect hop)
 });
 ```
 
+A `fetchGuard` replaces the built-in checks for the design's URLs. The client's own services skip both options, so a strict guard cannot cost the render its license or its fonts: the Polotno license check (`https://api.polotno.com`) and Google Fonts (`https://fonts.googleapis.com`, `https://fonts.gstatic.com`).
+
+Each blocked request is logged with `console.warn`, naming the URL and the rule that refused it.
+
+The guard is also published for your own fetches of design URLs:
+
+```js
+import { assertUrlAllowed, guardedFetch } from 'polotno-node/ssrf-guard';
+
+await assertUrlAllowed(url, { blockPrivateNetwork: true }); // throws FETCH_FAILED
+const res = await guardedFetch(url, { blockPrivateNetwork: true }); // checks every redirect hop
+```
+
+Hostnames are resolved and every address is checked. A hostile DNS server can still answer differently to the browser (DNS rebinding); to close that, also restrict egress at the network level.
+
 ### `attrs.assetLoadTimeout`
 
 You can add `assetLoadTimeout` attribute to `attrs` object. It will be used to set timeout for loading assets. By default it is 30000ms.