Security rules

A template runs on the same origin as the editor, so the compiler holds it to a few rules. Here they are, with the reason for each.

Why there are rules

The editor and the public site share one origin. An unescaped variable in a template is therefore a way into the editor: a script on the site origin can act as the signed-in editor.

So the compiler enforces, rather than recommends, where raw may be used and what a page may load.

Where raw is allowed

Only the five fragments head, content, jsonld, badge and guest_script may be output with | raw. The compiler holds to these rules:

  • The five fragments are wrapped in a SafeHtml marker before rendering. | raw accepts only a SafeHtml value. On anything else ({{ page.title | raw }}, {% echo site.name | raw %}, {% cycle x | raw %}, an assigned string) the engine throws TemplateError: "| raw is only allowed on head, content, jsonld, badge, guest_script".

  • {% assign t = content %}{{ t }} keeps the fragment safe. The marker travels with the value, so it is output unescaped. This is intended.

  • A filter after raw turns the fragment into a plain string, which is escaped again. {{ content | raw | upcase }} prints visible <SECTION ... text, never markup.

  • Using a fragment without | raw as the last filter ({{ content }}, {{ content.size }}, {{ content | upcase }}) is rejected before rendering, with a message saying so.

  • guest_script containing </script (any case) or <!-- is rejected.

  • Rendering is limited to 2 seconds and 1M memory units. Runaway loops fail with TemplateError.

Content Security Policy

Every compiled page starts its head fragment with <meta http-equiv="Content-Security-Policy" content="…">. The policy is CSP_POLICY from @piglet/core:

default-src 'self'; script-src 'self' 'sha256-<guest script hash>'; connect-src 'self'; img-src 'self' blob:; style-src 'self' 'unsafe-inline'; frame-src https://www.google.com; object-src 'none'; base-uri 'self'; form-action 'self'

The policy is what stops an escaping mistake in a template from letting a foreign script run on the site origin. In production the same policy also arrives as a response header, plus frame-ancestors 'none'. A browser enforces both, so a template cannot loosen the header by editing the meta.

What it means for you as a template author:

  • Inline styles are fine. <style> blocks and style="…" attributes are allowed ('unsafe-inline' in style-src).

  • Inline scripts are blocked. No <script>…</script> with code, no onclick= or onload= attributes, no javascript: URLs. Only the guest script, allowed by its hash, runs inline. <script type="application/ld+json"> is data, not code, and is not affected.

  • External scripts must be same-origin. Third-party CDNs (analytics, widgets) are blocked, so vendor a library into the template's public/ folder and load it with <script src="/_assets/<id>/lib.js" defer>. A template script runs on the editor's origin and can reach its write token: ship only code you have reviewed.

  • Images, fonts and stylesheets are same-origin too (default-src 'self'). Ship fonts in the template's public/ directory rather than loading Google Fonts. No data: images.

  • No <object> or <embed>, no <base> to another origin, and forms post only to the site itself.

  • Cloudflare features that inject scripts (Web Analytics auto-inject, Rocket Loader, Zaraz) are blocked by the policy. Leave them off.

To allow more, say a font CDN, the site owner must change the policy in both places: the header rule and the compiler. There is no per-template switch, on purpose.

Fonts and images

Ship fonts, images, scripts and stylesheets in packages/templates/<id>/public/. Deploy uploads them to _assets/<id>/<path>, and the layout references them as /_assets/<id>/fonts/a.woff2. Do not load a font or library from a CDN: the policy blocks it. Accepted types are woff2, webp, avif, png, jpg, jpeg, ico, js, mjs and css.

Images and links in content

  • All content strings (alt, caption, attribution, titles, bodies, icons, ids) are escaped by the renderers.

  • Images (an Image block, and images inside rich text) must match exactly /gallery/{folder}/{hash}.{ext}, with a folder of [a-z0-9-]{1,64}, a hash of [a-f0-9]{16} and an extension of webp, jpg or png. The path is at most 512 characters, with no % anywhere. Anything else is removed from rich text, or gives the empty figure.

  • Rich text JSON is sanitised before rendering: only known nodes, marks and attributes survive, and unknown types are dropped.

  • Links keep only http:, https: (with no username or password, so https://[email protected]/ is dropped), mailto:, /site-relative, #fragment or ?query hrefs, up to 2048 characters. Otherwise the link is removed and the text kept. Links always get rel="noopener", and target is only ever _blank.