typstream

Security

What a hostile document can and can't do to a page that renders it, the defences in each layer, and how to serve typstream under a strict Content-Security-Policy.

typstream renders Typst that a language model writes. This page explains what a hostile document can and can't do to a page that shows it, what holds that line, and how to serve typstream under a strict Content-Security-Policy.

Treat documents as untrusted code

Typst is a programming language, and the model writing it can be wrong or steered. A prompt can be injected through anything the model reads: a pasted article, a student's answer, a web page. Design as if every document were written by an attacker.

Threat model

The attacker is whoever controls the document text: the model, or someone steering it. A typstream server (@typstream/node) faces a second attacker: any client that can reach it.

What they want:

  • To run script in the host page's origin: steal its session, act as the user.
  • To make the browser fetch something: track the reader, leak data in a URL, probe the app's own origin.
  • To read files the app didn't mean to show: other documents' files, the app's static files, the server's disk.
  • To take the page down: hang the tab, exhaust memory, crash the worker for good.
  • To deceive the reader: links to other schemes, content that covers the app's own interface.

Where the document goes: text → the healer (main thread) → the engine worker (Typst compiled to WebAssembly) → an artifact (HTML, or page SVGs) → the renderer (DOM). Each step is a boundary below.

The engine's world: no files, no network, no host

Typst sees a virtual file system that the app fills. It holds the document, its preamble, the files the app passes (files), and the packages the app allows. There is no network, no environment and no clock beyond the date, and #read, #image, #json, #xml, #plugin and imports resolve inside that file system only:

A document triesWhat happens
#read("/etc/passwd"), #read("file:///etc/passwd")file not found (searched at /etc/passwd): paths name virtual files only
#read("../../../etc/passwd")path … would escape the project root
#image("https://tracker.example/pixel.png")file not found: a URL is just a path. The image shows as a placeholder, and nothing is fetched
reading another document's filesfile not found: each document's engine mounts only its own files
#import "@local/…", a package not on the allowlistpackage … is not allowed, and nothing is fetched
a wasm plugin importing a host functioncannot find definition for import env::fetch: plugins get only Typst's two protocol functions
an XML external entity, entity expansion, an SVG use bombrefused by Typst's XML and SVG parsers (unknown entity, entity loop, nodes limit)

Diagnostics name virtual paths only, never the server's or the machine's.

Packages come from an allowlist with pinned versions and integrity hashes, served from the app's own origin by default (@typstream/universe; see Typst packages). A server facing untrusted clients ignores the lists they send (trustClient: false, which @typstream/node sets), and the fixer modules they name (clientFixers: false, also set), since importing a module runs its code.

Images from the web are the one exception, and it is the app's choice: a resolveImage (such as fetchImages) runs on the main thread, where the app decides which paths to fetch and from which hosts. The engine still fetches nothing, so a @typstream/node server stays offline whatever its clients' documents name. An image URL is a way out for data the model read, so allow only hosts you trust; see Images.

Font catalogues (@typstream/google-fonts) are the other, also opt-in: a family a document names is downloaded if a catalogue the app gave the engine lists it. The document chooses only among the catalogue's families; the URLs come from the catalogue's index, never from the document, and a server facing untrusted clients ignores the catalogues they send (fontCatalogues: { trustClient: false }, which @typstream/node sets). Which family a document asked for is visible to the catalogue's host.

Keep the engine offline

Don't give typstream an engine whose file access goes to the network. typst.ts's FetchAccessModel, for example, turns every path a document names into a request to your origin.

Compute: the watchdog, traps and limits

Typst stops some runaways itself: infinite while loops, deep recursion, show rules that never terminate, and layout that doesn't converge (five attempts). It doesn't stop the rest: long finite loops, recursion with distinct arguments, memory bombs, and wasm plugins that never return (plugins have no fuel limit).

  • The watchdog gives every compile a budget (3 s streaming, 10 s final). Past it, the main thread terminates the worker and continues on a fresh one. Three strikes stop live preview; the finished document compiles once more, and then the fallback ladder finds the blocks that hang and shows them as error boxes.
  • Traps. A Typst panic, running out of wasm memory, or content nested so deep that the wasm stack overflows ends the worker without an answer. The client counts it like a timeout and replaces the worker. The stack overflow surfaces as the host's error (RangeError in V8 and JavaScriptCore, InternalError in SpiderMonkey), not a wasm trap, and leaves the instance unusable, so the server treats it as fatal too.
  • Memory. Typst's caches are evicted after every compile. A worker that reports more than 256 MiB is replaced (recycleBytes).
  • Limits (createEngine({ limits })):
    • maxLength (default 1 MiB of UTF-16 code units): longer input isn't healed or compiled, which protects the main thread. The document reports too-large, keeps its last render, and refuses exports until set() or reset() brings it back under the limit.
    • livePages (default 100): a streaming compile with more pages stops live preview (too-complex). The finished document compiles in full.
    • @typstream/node refuses documents over maxTextLength (1,000,000).

Output: what reaches the DOM

Typst writes what html.elem asks for, verbatim: <script>, onerror=, href="javascript:…", <iframe srcdoc>, <base>, <meta http-equiv=refresh>. The renderers are where these stop.

HTML target

The renderer parses markup into an inert <template>, so nothing runs or loads while it is parsed. It cleans that tree with an allowlist sanitizer and moves the cleaned nodes into the page; nothing is serialized and parsed again, so mutation XSS can't happen. The sanitizer keeps:

  • the HTML elements Typst writes, MathML Core and drawing SVG;
  • links to http(s), mailto and #fragments (external links get rel="noopener noreferrer"), read the way URL parsers read them (java\tscript: is javascript:);
  • images from data:image/* and blob: only;
  • CSS that loads nothing (no url(), image-set(), expression(), bindings) and isn't position: fixed;
  • the classes Typst writes (its MathML and bibliography classes), the engine's typstream-* placeholders, and the ones plugins list (html-compat's ts-*, edu's edu-*).

Everything else goes: scripts, styles, frames, objects, forms, on* handlers, data-*, name, is, srcset, ping, SVG animation, foreignObject, and every other class, so a document can't take on your page's styles (Tailwind's fixed inset-0 z-50, your app's button) or what your scripts attach to a class. Ids get a per-renderer prefix, so a label can't clobber a global (window.location). Plugins can allow more tags, attributes and classes (the sanitize facet), but never handlers, scripts or attributes that load something. An attribute a plugin allows on every element (allowAttrs["*"]) applies to HTML elements only and can't be href or src; href and src allowed for one tag go through the same URL checks as Typst's links and images, and an allowed name gets the id prefix, so <img name="cookie"> can't clobber document.cookie.

The document also stays inside its element. A document can still lay a box over its own content (CSS such as position: absolute, negative margins or transform has legitimate uses), and your page's CSS can still reach the elements it writes. So the renderer's stylesheet clips the root, .typstream:

:where(.typstream) {
  position: relative;
  overflow: clip;
  clip-path: inset(0);
}

clip-path clips the painting and the clicks of everything inside, position: fixed boxes included, so nothing the document draws covers your app outside its element. overflow: clip keeps what it overflows with from making your page scroll. Neither changes layout (no new formatting context, so margins collapse as before). The renderer lays the document out on pages (.typstream-pages): the document is then in its flow (.typstream-flow), over the sheets, which clips the same way, its box the pages' text and margins, so what reaches past a page's edge, such as a box placed outside it, is cut off there. Scroll the element itself if you prefer: a rule of yours on .typstream wins over :where(), and a scrolling ancestor clips as well. If you pass injectStyles: false, ship these rules with the rest of htmlRendererCss.

Render islands

A render island is your code running on data a document wrote. The renderer reads a typstream-island marker's name and JSON before sanitizing (the sanitizer keeps the element, none of its attributes) and mounts an island only for a name a loaded plugin declares and your app gave a component for, so a document can't mount a component you didn't pair with its plugin. The data goes through the plugin's parse first: a marker whose JSON is over 64 KB, doesn't parse or doesn't pass keeps its Typst fallback, as do markers past 50 per document. An island gets files only through IslandProps.file, the bytes the document already has; it fetches nothing the document names. Write islands to treat their data as text, never as markup or URLs to load: @typstream/mindmap renders labels through React and checks colours and sizes before they reach a style.

Paged target

Pages are typst-svg's output: glyphs as paths, images as data: URLs, and attribute values escaped by its XML writer. A page lives in its own shadow root, where the app's CSS can't reach it. Each page is parsed into an inert <template> first, and the view keeps links to http(s) and mailto only, and images with data: URLs only, before the page is inserted. It trusts typst-svg's serializer for the rest. The hostile documents check that on every Typst upgrade.

Standalone HTML exports

Standalone HTML exports (standaloneHtml from @typstream/dom) aren't sanitized. Files laid out as the pages (standalonePages, which a mounted document's exportHtml() uses) hold what the HTML renderer showed, sanitized, serialized again. Either file carries its own Content-Security-Policy (no scripts, no network, no forms), which stops what the document wrote in Chromium, Firefox and WebKit, and markup the serializer and a reader's parser would disagree about (mutation XSS) too. See Exports.

The engine's doc.exportHtml() (and @typstream/node's render(source, "html")) return Typst's HTML as it is: unsanitized, and without that policy. Wrap it with standaloneHtml before you offer it as a file, and never insert it into your page.

Privacy

Nothing is fetched from third parties by default. The engine, its fonts and packages come from the app's origin and are cached in Cache Storage. @typstream/google-fonts is the exception when you add it: readers' browsers download the families documents use from cdn.jsdelivr.net, unless you mirror them. typstream sends no telemetry; the events it reports go only where your app sends them.

Content-Security-Policy

typstream works under a strict policy: no inline script, no inline style, no eval and Trusted Types enforced, with everything served from your own origin. typstream's CI serves a page with exactly this policy and opens it in Chromium, Firefox and WebKit, failing on any violation:

Content-Security-Policy
default-src 'none';
script-src 'self' 'wasm-unsafe-eval';
worker-src 'self';
connect-src 'self';
img-src 'self' data: blob:;
font-src 'self';
style-src 'self';
base-uri 'none';
form-action 'none';
frame-ancestors 'none';
require-trusted-types-for 'script';
trusted-types typstream

What each directive is for:

DirectiveWhy typstream needs it
script-src 'wasm-unsafe-eval'The engine is WebAssembly. Compiling a module needs this keyword: it allows WebAssembly.compile*, not eval. The worker gets the policy from its own response, so send the header on the worker script too.
worker-src 'self'The engine runs in a module worker loaded from your origin (engineWorker()). Bundling setups that inline workers as blob: URLs need blob: here.
connect-src 'self'The worker fetches the wasm, the fonts (script fonts lazily, when a document uses them) and package tarballs. Add the origin if you serve these from a CDN (Self-hosting), the WebSocket's origin for a remote engine, and https://cdn.jsdelivr.net for Google Fonts (the worker and the HTML renderer download the families documents name).
img-src data: blob:Typst writes a document's images as data: URLs, and apps may pass blob: ones.
font-src 'self'registerMathFont loads New Computer Modern Math for MathML through the FontFace API.
style-src 'self'Enough. The renderers inject their CSS as constructed stylesheets (adoptedStyleSheets), and apply the inline styles of Typst's HTML (layout from html-compat, fills, colours) through the CSSOM. A strict policy refuses style attributes parsed from markup, so they never reach the parser. Browsers without constructed stylesheets (Safari before 16.4) get a <style> element instead, which needs 'unsafe-inline'.
require-trusted-types-for 'script', trusted-types typstreamOptional: Trusted Types make script sinks such as innerHTML refuse plain strings. typstream passes its markup and the engine worker's URL through one policy named typstream, so list that name next to your app's own policies.

Not needed: 'unsafe-eval', 'unsafe-inline', cross-origin isolation (COOP/COEP), or any third-party origin.

Trusted Types

With require-trusted-types-for 'script', the browser refuses strings at script sinks unless a Trusted Types policy made them. typstream has three, and sends all of them through one policy named typstream, created the first time one is used:

  • the HTML renderer's markup, parsed into an inert <template> (nothing runs or loads) and sanitized before it is moved into the page;
  • each SVG page, parsed the same way, its links and images filtered before the page is inserted (canvas pages parse no markup: their links are built as elements, with the same filter, and their images only load from data: URLs);
  • the engine worker's URL (engineWorker()).

The policy passes values through unchanged: what makes them safe is that markup is only ever parsed inert and cleaned, and that the worker URL is the one your bundler emitted.

Allow the name in trusted-types, next to your own policies: trusted-types my-app typstream. A page can create a policy name only once. If something else has already created typstream (or the directive doesn't list it), typstream passes plain strings instead: that works without enforcement, or with a default policy, and fails with the browser's TrustedHTML error otherwise. Two copies of @typstream/core in one bundle each try to create it, so deduplicate them, or add 'allow-duplicates' to the directive.

Sending the header

Prefer the header to a <meta> tag: frame-ancestors is ignored in <meta>, and the header covers the worker script too. Keep the policy in one place:

csp.mjs
export const CSP = [
  "default-src 'none'",
  "script-src 'self' 'wasm-unsafe-eval'",
  "worker-src 'self'",
  "connect-src 'self'",
  "img-src 'self' data: blob:",
  "font-src 'self'",
  "style-src 'self'",
  "base-uri 'none'",
  "form-action 'none'",
  "frame-ancestors 'none'",
  "require-trusted-types-for 'script'",
  "trusted-types typstream",
].join("; ");

The dev server and vite preview send the policy, so what works in development works behind it:

vite.config.mjs
import { defineConfig } from "vite";
import { CSP } from "./csp.mjs";

const headers = { "Content-Security-Policy": CSP };

export default defineConfig({
  server: { headers },
  preview: { headers },
  // The engine worker is a module worker; its chunks must be ES modules too.
  worker: { format: "es" },
  // Vite inlines small assets as data: URLs; keep fonts and package tarballs as files.
  build: { assetsInlineLimit: 0 },
});

In production, send the same header from your server or static host.

For any other static host, use its header configuration.

Known gaps

  • The paged view trusts typst-svg's serializer (above): the hostile documents run again on every Typst upgrade, as they do for the plugin sandbox.

How this is tested

A corpus of hostile documents (reads, images, imports, plugins and XML outside the sandbox; links to other schemes; html.elem scripts, handlers, frames, forms, CSS and overlays; runaway plugins; content nested too deep; huge dimensions) streams into the real renderers in CI, in Chromium, Firefox and WebKit, in both targets, along with the sanitizer's XSS and mutation-XSS cases and the strict-CSP page above.

On this page