In a template engine that escapes interpolated values by default, what does a raw-output marker disable, and what must you then guarantee?

Auto-escaping is the single feature that makes server-side templating safe by default, and the raw-output marker is the documented hole in it. Understanding exactly what the marker switches off — and what it does not — is the difference between a deliberate, reviewed exception and a script-injection hole. ## What auto-escaping actually does When the engine reaches a placeholder it evaluates the expression, converts the result to text, and then **encodes** that text for the output it is writing before appending it to the response buffer. Encoding replaces the characters that would otherwise be read as markup syntax with their inert representations, so a value containing angle brackets, quotes or ampersands renders as those visible characters instead of becoming structure. Two properties are worth stating precisely: - Escaping happens **at write time, per placeholder**, not to the model and not to the stored data. The same value can be written twice in one page and encoded differently each time. - Escaping is **position-dependent**. Text between elements, a quoted attribute value, an unquoted attribute value, a URL-valued attribute and a script or style block are parsed by different rules, so the correct encoding is not one fixed transformation. ## Contextual versus single-mode engines | Engine behaviour | What it encodes | What it still gets wrong | |---|---|---| | Contextual auto-escaping | picks the encoding from the position the placeholder sits in | little, while the surrounding markup is static and parseable at compile time | | Single-mode auto-escaping | one document-level encoding everywhere | values placed in script blocks, unquoted attributes or URL-valued attributes | | No auto-escaping (opt-in) | nothing unless the template asks | everything a template author forgets, which is the failure mode of "remember to escape" | This is the honest generic statement: frameworks differ here — some engines track the position and vary the encoding, others apply a single encoding and leave the rest to the author, and a few still default to no escaping and require an explicit call. Knowing which kind you are on decides how much the default is really buying you. ## What the raw marker turns off, precisely The marker applies to **one interpolation**. It does not disable escaping for the template, the layout, or the included fragments — it says that this particular string is already markup and should be appended verbatim. Consequences: - Whatever produced the string is now the security boundary. If any part of it derives from user input without transformation, the user can contribute markup and script. - The marker composes badly with concatenation. Building a string out of a trusted wrapper plus an untrusted value and then marking the whole thing raw is the most common way the hole opens; the untrusted half is carried through the marker. - Some engines represent trust as a **type** rather than a marker: a value of a "safe markup" type is written unescaped and any plain string is escaped. That is strictly better, because trust travels with the value and survives being passed into a fragment instead of being a property of the call site. ## Making a raw output defensible When the requirement is genuine — stored rich text, a preformatted mail body, markup assembled by your own component code — the following discipline keeps it reviewable: 1. **Sanitize on the way to the page**, with a parser-based sanitizer that emits an allow-list of elements and attributes, rather than trying to remove the dangerous parts of a string with pattern matching. 2. **Narrow the marker** to the smallest expression. `raw(article.body)` is auditable; a raw block wrapping a header, a nav and a body is not. 3. **Do not place raw output in a position the sanitizer did not assume.** A sanitizer that produces safe element content produces nothing you can drop unquoted into an attribute or into a script block. 4. **Make it greppable.** A single well-known spelling of the marker means a reviewer or a lint rule can enumerate every exception in the codebase; several spellings and a global switch mean nobody can. ## Where the hatch leaks in practice - **Global disable.** Turning auto-escaping off for a directory or a build "because the templates are reviewed" converts every placeholder into an exception and removes the property you were relying on. - **Double-encoding workarounds.** A value encoded once by application code and again by the engine renders visible entity text; the wrong fix is to mark it raw, and the right fix is to stop encoding it early and let the engine do it once. - **Rich text stored as markup.** If a value is stored as markup, every consumer must treat it as markup — a second page that renders the same field escaped shows the tags, and a third that renders it raw without sanitizing inherits the hole. - **Values reaching a template through a fragment parameter.** A call-site marker says nothing about what happens two fragments deeper; trust-carrying types survive that journey, bare markers do not.