Skip to content

Resource loading and security

A document can reference other files: stylesheets (<link rel="stylesheet">, @import), images (<img>, <object>, <embed>, SVG <image>, CSS url()), web fonts (@font-face) and attachments (<link rel="attachment">). kolinsky loads all of them, and the input itself when it is a URL, through one fetcher, under an access policy that you set per call. When the documents you render are not your own, the policy decides what they can read.

Read directly, outside the fetcher and the policy, are only what you name yourself: an input given as a file path, the fonts you add to the engine, the system fonts and the attachments of the PDF options.

What the default fetcher loads

URLs Loaded
data: always
file: every file the process can read, or only the files inside root when it is set
http:, https: never by default; when the network is allowed, all or the URLs that match a pattern
any other scheme never (resource.unsupported); a custom fetcher can serve it

Within one call each URL is loaded at most once, and the answer (a failure included) is used for every reference to it. Nothing is cached between calls.

A resource that cannot be loaded is not an error: it is skipped and reported as a resource.* diagnostic (resource.not-found, resource.denied, resource.timeout, resource.too-large, resource.unsupported, resource.failed, resource.invalid) at the element or declaration that references it. Only the input itself and the user stylesheets you pass fail the call when they cannot be loaded. Use strict mode to fail on missing resources.

Base URLs

Relative references resolve against the document's base URL: the file's URL for a file input, the final URL for a URL input, and for HTML text the base URL you pass with it. A <base href> element replaces it. HTML text without a base URL cannot resolve relative references; they give resource.unresolved. On the command line, --base-url sets the base URL of every input (standard input defaults to the working directory).

Network access

The network is off by default: every http: and https: URL is denied before any connection is made. Allow it for all URLs (--allow-net, allow_network=True, NetworkAccess::AllowAll), or only for the URLs that match one of a list of patterns (--allow-net=PATTERN, repeatable).

A pattern is scheme://host[:port][/path]:

  • the scheme is http or https and must be the URL's scheme;
  • the host is compared ignoring case; *.example.com matches every host below example.com (cdn.example.com, a.b.example.com) but not example.com itself;
  • without a port the URL must use the scheme's default port; with one it must use that port;
  • a path is a prefix of the URL's path: /assets/ matches everything below it, /img matches /img, /img/a.png and /images. The query is ignored.
Pattern Matches Does not match
https://example.com https://example.com/a.css http://example.com/a.css, https://cdn.example.com/a.css
https://*.example.com https://cdn.example.com/x.png https://example.com/x.png
https://example.com:8443/assets/ https://example.com:8443/assets/logo.svg https://example.com/assets/logo.svg

A * anywhere else, user information, an empty host and other schemes are invalid patterns and are rejected before anything is loaded. Redirects are followed (up to 10) and each target is checked against the policy again.

The root directory

With root (--root DIR) set, a file: URL is loaded only when the file, with symbolic links and .. resolved, is inside that directory. A file outside the root is denied, also when it does not exist, so a document cannot find out which files exist outside it. Without root every file the process can read is allowed. The root does not limit the input file, user stylesheets given as paths, fonts or the attachments of the PDF options.

Limits

timeout (--timeout SECONDS, 30 seconds by default) bounds each fetch, connection and redirects included. max_resource_size (--max-resource-size, 64 MiB by default, with the suffixes K, M and G on the command line) bounds the size of each resource after decoding. A resource over a limit is abandoned (resource.timeout, resource.too-large).

The options together, on the command line:

kolinsky render hello.html -o hello.pdf --allow-net=https://cdn.example.com/assets/ --allow-net=https://*.example.org --root . --timeout 10 --max-resource-size 16M

In Rust, the policy is RenderOptions::access:

use kolinsky::{Engine, Input, NetworkAccess, PdfOptions, RenderOptions};
use std::time::Duration;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut options = RenderOptions::default();
    // Only these hosts and paths; every other http: and https: URL is denied
    options.access.network = NetworkAccess::AllowList(vec!["https://cdn.example.com/assets/".parse()?, "https://*.example.org".parse()?]);
    // file: URLs only inside the current folder
    options.access.root = Some(std::env::current_dir()?);
    options.access.timeout = Duration::from_secs(10);
    options.access.max_resource_size = 16 << 20;

    let rendered = Engine::new().render(Input::Path("hello.html".into()), &options, &PdfOptions::default())?;
    std::fs::write("hello.pdf", rendered.output)?;
    Ok(())
}

In Python, the same fields are options:

from pathlib import Path

import kolinsky

options = kolinsky.Options(
    allow_network=("https://cdn.example.com/assets/", "https://*.example.org"),
    root=".",
    timeout=10.0,
    max_resource_size=16 * 1024 * 1024,
)
result = kolinsky.render(Path("hello.html"), options=options)
Path("hello.pdf").write_bytes(result.pdf)

Custom fetchers

An engine can be built with a fetcher of your own. It sees every request with its URL, its kind (document, stylesheet, image, font, attachment) and the call's access policy, and it can answer from anywhere: a database, an archive, the application's own assets under a scheme like app://. For the URLs it does not handle it calls the default fetcher, which applies the policy as usual.

The engine trusts the answers of a custom fetcher: what it serves itself is not checked against the access policy, so it is responsible for its own rules. A fetcher can also remap a URL and pass the new one to the default fetcher (request.with_url(&url) in Rust, request.default(url) in Python); the remapped URL is then checked against the policy. The URL of the resource it returns is the base for the references inside the resource.

use kolinsky::{DefaultFetcher, Engine, FetchError, FetchErrorKind, FetchRequest, Fetcher, Input, PdfOptions, RenderOptions, Resource};

const LOGO: &str = r##"<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 10 10"><circle cx="5" cy="5" r="4" fill="#c25129"/></svg>"##;

/// Serves `app:` URLs from memory and hands every other URL to the default fetcher, which applies the access policy.
struct AppFetcher {
    inner: DefaultFetcher,
}

impl Fetcher for AppFetcher {
    fn fetch(&self, request: &FetchRequest<'_>) -> Result<Resource, FetchError> {
        if request.url.scheme() == "app" {
            return match request.url.as_str() {
                "app://logo.svg" => Ok(Resource { bytes: LOGO.as_bytes().to_vec(), content_type: Some("image/svg+xml".into()), url: request.url.clone() }),
                other => Err(FetchError::new(FetchErrorKind::NotFound, format!("no asset {other}"))),
            };
        }
        self.inner.fetch(request)
    }
}

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let engine = Engine::builder().fetcher(AppFetcher { inner: DefaultFetcher::new() }).build();
    let rendered = engine.render(Input::Path("app.html".into()), &RenderOptions::default(), &PdfOptions::default())?;
    assert!(rendered.diagnostics.is_empty(), "{:?}", rendered.diagnostics);
    std::fs::write("app.pdf", rendered.output)?;
    Ok(())
}

In Python, a fetcher is a callable that takes a kolinsky.Request and returns a kolinsky.Resource. It fails by raising kolinsky.KolinskyFetchError with a kind (not-found, denied, timeout, too-large, unsupported, failed); any other exception counts as failed.

from pathlib import Path

import kolinsky

LOGO = b'<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 10 10"><circle cx="5" cy="5" r="4" fill="#c25129"/></svg>'


def fetcher(request: kolinsky.Request) -> kolinsky.Resource:
    # app: URLs from memory, everything else through the default fetcher and the access policy
    if request.url == "app://logo.svg":
        return kolinsky.Resource(LOGO, content_type="image/svg+xml")
    if request.url.startswith("app:"):
        raise kolinsky.KolinskyFetchError(f"no asset {request.url}", kind="not-found")
    return request.default()


engine = kolinsky.Engine(fetcher=fetcher)
result = engine.render(Path("app.html"))
Path("app.pdf").write_bytes(result.pdf)

Untrusted documents

For documents you do not control, keep the network off or allow only the hosts you need, set root to the directory of the document's assets, and keep the limits low enough for your service. Rendering is CPU-bound and runs in your process; run untrusted renders where a long or large job cannot affect other work, and use strict mode when a missing resource should fail the job.