Eyrie-Templates/THREAT_MODEL.md

# Eyrie Templates — Threat Model (Draft)

Purpose: identify assets, threats, and controls relevant to a server‑side PHP templating engine and define baseline mitigations.

## 1. Assets

- Template sources (files and compiled cache outputs)
- Rendered HTML output delivered to clients
- Template context data (user data, secrets if accidentally passed)
- Component definitions/renderers and their configuration
- Helper/filter registry and configuration
- Loader configuration (roots, namespaces)
- Cache directory and compiled artifacts
- Error logs and diagnostics

## 2. Actors

- Application developers (trusted, may misconfigure)
- End users (untrusted input surfaces)
- Attackers supplying malicious input
- System administrators (manage deployment and FS perms)

## 3. Trust boundaries

- Between untrusted user input and template rendering
- Between template engine and filesystem (loaders, cache)
- Between engine and helper/filter callables (application code)
- Between dev and prod environments (verbosity, paths, timings)

## 4. Entry points and attack surfaces

- Template variables/expressions from request‑derived data (XSS)
- Helper/filter parameters (command/code injection via helpers)
- Component props/attributes (injection vectors; type confusion)
- Template name resolution (path traversal, namespace bypass)
- Include/extends directives (recursive includes, deep inheritance)
- Component trees (deep recursion/nesting)
- Large templates or pathological inputs (parser/render DoS)
- Cache poisoning or disclosure (incorrect perms or keying)
- Error pages and stack traces (info leakage)

## 5. Threats and mitigations

- Reflected/stored XSS in output
  - Default auto‑escaping with context modes (`html`, `attr`, `url`, `js`)
  - `safe` must be explicit and narrowly scoped
  - Security lint/checks to flag `safe` usage
- Path traversal via loader
  - Normalize and resolve paths; reject `..` and absolute paths unless mapped
  - Restrict to configured roots; support namespaces with fixed roots
- Code execution via helpers/filters
  - Only whitelisted callables registered by application
  - No evaluation of template strings as PHP; no reflection access
  - Optionally sandbox helpers with contracts and safe value types
- Code execution or SSRF via component renderers
  - Components implement a constrained interface; no filesystem/network access by default
  - Validate and sanitize props before use; avoid passing raw props to sinks
  - Enforce a strict registry: only explicitly added components are callable
- DoS via deep inheritance/recursion or huge loops
  - Limits: include/extends depth; loop iteration caps; template/token size limits
  - Watchdog timeouts for parse/render
  - Component nesting/recursion depth caps and per‑render time budgets
- Cache tampering/leakage
  - Cache dir perms 0700; atomic writes; validate cache keys (include engine version and options)
  - Avoid executing cache files; treat as data
- Information disclosure via errors
  - Configurable verbosity; hide paths/snippets in production
  - Structured error types without sensitive context values
- SSRF/RFI via helpers/filters
  - No network/file IO in templates; helpers must not fetch remote resources by default
  - Apply same restrictions to components

## 6. Assumptions

- Templates are developer‑authored and trusted; user‑generated templates are out of scope.
- Application controls helper registrations; helpers conform to safe contracts.
- Deployment applies standard OS hardening (FS perms, no public cache dirs).

## 7. Security requirements (binding)

- Auto‑escaping enabled by default and cannot be globally disabled in production builds
- Loader prevents traversal; cannot escape configured roots
- Depth/size/time limits are configurable with safe defaults
- Distinct dev/prod modes, with safe prod defaults
- No eval of template source; no direct PHP execution from templates
- Components are pure render units; cannot mutate outer context; registered explicitly

## 8. Validation and testing

- XSS test corpus across HTML, attribute, JS, and URL contexts
- Fuzz tests for parser stability and timeouts
- Unit tests for loader normalization and traversal blocking
- Integration tests for cache directory perms and keying
- Component test suite for prop escaping, type validation, and recursion limits

## 9. Open items

- Define safe value wrapper interface
- Decide on strict‑variables default (on/off)
- Finalize default limits (include depth, loop max, template size)