This page documents the threat model and defenses for the multi-file template system. Single-string template.Compile(src) has no loader and no input other than the source string, so this page applies only to code that uses NewHTMLSet or NewTextSet.

Trusted: template authors. Templates you ship with your application are assumed to be code you control. This library does not sandbox template-level logic (infinite loops in {% for %}, large string manipulations, etc.) — Django, Jinja2, and Liquid all take the same position.

Untrusted: everything that flows into a template through data or dynamic paths. Specifically:

Every Loader.Open implementation must call ValidateName(name) as the first thing it does. This is a stricter version of fs.ValidPath:

func ValidateName(name string) error {
    if !fs.ValidPath(name) {      // rejects "", "..", absolute, trailing /
        return ErrInvalidTemplateName
    }
    if strings.ContainsAny(name, "\\\x00") {  // plus backslash and NUL
        return ErrInvalidTemplateName
    }
    return nil
}

Why stricter than fs.ValidPath? fs.ValidPath allows backslash and NUL (they're valid UTF-8 code points that Go considers non-path- significant on Unix). We reject them universally to:

• Prevent Windows path aliases (C:\foo, \\server\share) from ever reaching an FS that might interpret them.
• Prevent NUL-byte injection attacks that truncate paths when passed to C syscalls.

NewDirLoader uses Go 1.24+'s os.Root primitive:

root, err := os.OpenRoot(dir)
// ...
f, err := root.Open(name)

os.Root guarantees:

• Symbolic links cannot cross the root boundary at the syscall level. If a file inside the root is a symlink pointing outside, the Open call fails.
• .. and absolute paths are rejected again at the OS layer, forming a second line of defense after Layer 1.
• TOCTOU is closed: it uses openat2 or O_NOFOLLOW primitives, not "check then open".

This is stronger than os.DirFS, which Go's documentation explicitly notes "does not prevent symbolic links from referring to files outside the directory."

NewFSLoader(fs.FS) assumes the caller has already picked a sandboxed filesystem. Safe sources include:

• embed.FS — compiled into the binary, immutable
• fstest.MapFS — in-memory test double
• archive/zip.Reader — bounded archive

Explicitly non-safe source: os.DirFS(path). If you pass this, the library cannot prevent symlink escape — you are opting into the less-strict Go primitive. The documented use case is developer workflows (theme dev, monorepo sharing) where you trust the local filesystem.

ChainLoader prepends layer0:, layer1:, ... to each layer's resolved name, so:

• User layouts/blog.html and theme layouts/blog.html get distinct cache entries (layer0:layouts/blog.html vs layer1:layouts/blog.html)
• A macOS case-insensitive collision (Header.html vs header.html) produces two cache entries referring to the same underlying file — a small amount of wasted memory, but no correctness bug.

Multiple defenses against runaway recursion:

1. Parse-time circular detection (Set.parsing map). When parsing template A, any static {% include "B" %} in A where B is already mid-parse is downgraded to lazy (runtime) mode. This enables recursive tree-walk patterns while preventing parse-time infinite recursion.
2. Parse-time extends circular detection. Unlike include, extends cannot be lazy — circular extends returns ErrCircularExtends.
3. Runtime include depth cap: maxIncludeDepth = 32. Deeper nesting returns ErrIncludeDepthExceeded before the Go stack overflows.
4. Runtime extends depth cap: maxExtendsDepth = 10. Returns ErrExtendsDepthExceeded.

Both caps are hard-coded constants. They are safety nets, not performance tunables. If your architecture legitimately needs more, something is probably wrong.

NewHTMLSet wires ec.autoescape = true, which causes OutputNode.Execute to pipe every {{ expr }} output through filter.Escape before writing — unless the underlying value is a SafeString.

SafeString is opt-in, not opt-out:

• The safe filter wraps a value: {{ content | safe }}
• Go code can construct one directly: template.SafeString("<p>trusted</p>")
• The HTMLSet overrides of escape, escape_once, and h return SafeString, so {{ x | escape }} doesn't double-escape.

Conservative downgrade: if any non-safe-aware filter runs on a SafeString, the wrapper is stripped and the value becomes plain string again (subject to auto-escape). This prevents "I thought I was safe" XSS bugs like {{ user_input | safe | upper }}. The only safe-aware filters in v1 are safe and (in HTMLSet) the escape family.

Template authors can write infinite loops ({% for x in items %} where items is mutated to never terminate), allocate arbitrary amounts of memory via filters, or traverse the data context to leak information. This is by design — template authors are trusted.

If you need to run untrusted templates (a hosted CMS, a sandboxed scripting feature), this library is not a safe choice. Use a dedicated sandbox (e.g. sanitize + timeout + memory cap around a separate process).

NewHTMLSet auto-escapes for an HTML text context: <, >, &, ', ". It does not do context-aware escaping for:

• JavaScript strings (<script>var x = "{{ user }}"</script>)
• CSS identifiers (<style>.{{ class }} { ... }</style>)
• URL components (<a href="{{ url }}"> is OK for text-context, but javascript: schemes are not filtered)
• JSON embedded in HTML attributes

For these contexts, use filter.Escape only as a baseline. Treat embedded JS/CSS/URL values as separate escape problems and solve them at the data layer before passing to the template.

This is a template engine. It doesn't know who the user is, what they're allowed to see, or whether this request is authorized. Do not use {% if user.is_admin %} as a security boundary — check at the controller layer before rendering.

The library ships a security matrix covering T1–T11 in security_test.go. When writing a custom loader, run the same matrix against it:

func TestMyLoader_Security(t *testing.T) {
    t.Parallel()

    loader := NewMyLoader(...)
    invalid := []string{
        "../etc/passwd",
        "/etc/passwd",
        "a\\b",
        "a\x00b",
        "C:\\x",
        "\\\\server\\share",
        "",
        ".",
    }
    for _, name := range invalid {
        if _, _, err := loader.Open(name); !errors.Is(err, ErrInvalidTemplateName) {
            t.Errorf("Open(%q) should return ErrInvalidTemplateName, got %v", name, err)
        }
    }
}

If your loader touches the real filesystem, also add the symlink- escape test from security_test.go (TestDirLoader_SymlinkEscape_Rejected).