URL Access Policy

When templates contain dynamic images with URL sources, the library fetches those URLs during PDF generation. The URL access policy controls which URLs are allowed, protecting your server from SSRF (Server-Side Request Forgery) attacks.

Default protection

The library blocks private and internal URLs by default — no configuration needed:

• Loopback: 127.x.x.x, localhost, [::1]
• Private networks: 10.x.x.x, 172.16-31.x.x, 192.168.x.x
• Link-local / cloud metadata: 169.254.x.x
• Non-HTTP protocols: file://, ftp://, etc.

All public HTTP and HTTPS URLs are allowed.

Adding restrictions

Use createUrlAccessPolicy to layer extra rules on top of the built-in protection. The default private/internal IP blocking is always applied first.

import { configure, createUrlAccessPolicy } from "@pdfsamurai/pdfsamurai-js";

configure({
  apiKey: "your-api-key",
  urlAccessPolicy: createUrlAccessPolicy({
    allowedDomains: ["cdn.myapp.com", "images.myapp.com"],
    requireHttps: true,
  }),
});

Options

Name	Type	Default	Description
allowedDomains	string[]	—	Only allow these hostnames. If omitted, all public domains are allowed
requireHttps	boolean	false	Block plain HTTP, only allow HTTPS

Full control

For complete control, pass a raw callback to configure. This replaces the defaults entirely — you are responsible for all validation:

import { configure } from "@pdfsamurai/pdfsamurai-js";

configure({
  urlAccessPolicy: (url) => url.startsWith("https://cdn.myapp.com/"),
});

You can also compose your logic with the built-in policy to keep the default SSRF protection while adding your own rules:

import { configure, defaultUrlAccessPolicy } from "@pdfsamurai/pdfsamurai-js";

configure({
  urlAccessPolicy: (url) =>
    defaultUrlAccessPolicy(url) && url.includes("trusted.com"),
});