Fix template autoescape, CAS single-return, and WebSocket SHA-1 hardening

Default Jinja rendering to autoescape=True and auto-detect HTML targets so
user-supplied values can never inject raw markup. ContentStore.put /
put_bytes now route through a single _write_atomic helper (single return
point). The WebSocket handshake's RFC 6455 SHA-1 call passes
usedforsecurity=False with a nosec tag since it is not a security primitive.

Author: JE-Chen

automation_file/core/content_store.py

@@ -11,7 +11,7 @@
 import hashlib
 import os
 import shutil
-from collections.abc import Iterator
+from collections.abc import Callable, Iterator
 from pathlib import Path
 from typing import IO
 
@@ -48,36 +48,28 @@ def put(self, source: str | os.PathLike[str]) -> str:
             raise CASException(f"source is not a file: {src}")
         digest = self._hash_file(src)
         target = self.path_for(digest)
-        if target.exists():
-            return digest
-        target.parent.mkdir(parents=True, exist_ok=True)
-        tmp = target.with_suffix(target.suffix + ".tmp")
-        try:
-            shutil.copyfile(src, tmp)
-            os.replace(tmp, target)
-        except OSError as error:
-            if tmp.exists():
-                tmp.unlink(missing_ok=True)
-            raise CASException(f"failed to ingest {src}: {error}") from error
+        if not target.exists():
+            self._write_atomic(target, lambda tmp: _copyfile(src, tmp))
         return digest
 
     def put_bytes(self, data: bytes) -> str:
         """Ingest raw bytes and return the hex digest."""
         digest = hashlib.new(_HASH, data).hexdigest()
         target = self.path_for(digest)
-        if target.exists():
-            return digest
+        if not target.exists():
+            self._write_atomic(target, lambda tmp: _write_bytes(tmp, data))
+        return digest
+
+    def _write_atomic(self, target: Path, writer: Callable[[Path], None]) -> None:
         target.parent.mkdir(parents=True, exist_ok=True)
         tmp = target.with_suffix(target.suffix + ".tmp")
         try:
-            with open(tmp, "wb") as fh:
-                fh.write(data)
+            writer(tmp)
             os.replace(tmp, target)
         except OSError as error:
             if tmp.exists():
                 tmp.unlink(missing_ok=True)
             raise CASException(f"failed to store blob: {error}") from error
-        return digest
 
     def open(self, digest: str) -> IO[bytes]:
         """Open the stored blob for binary read."""
@@ -125,3 +117,12 @@ def _hash_file(self, path: Path) -> str:
             for chunk in iter(lambda: fh.read(_CHUNK), b""):
                 hasher.update(chunk)
         return hasher.hexdigest()
+
+
+def _write_bytes(target: Path, data: bytes) -> None:
+    with open(target, "wb") as fh:
+        fh.write(data)
+
+
+def _copyfile(src: Path, dst: Path) -> None:
+    shutil.copyfile(src, dst)

automation_file/local/templates.py

@@ -15,10 +15,21 @@
 from automation_file.exceptions import TemplateException
 
 
-def render_string(template: str, context: dict[str, Any], *, use_jinja: bool = True) -> str:
-    """Render ``template`` against ``context`` and return the string result."""
+def render_string(
+    template: str,
+    context: dict[str, Any],
+    *,
+    use_jinja: bool = True,
+    autoescape: bool = True,
+) -> str:
+    """Render ``template`` against ``context`` and return the string result.
+
+    ``autoescape=True`` (the default) HTML-escapes substituted values when the
+    Jinja2 engine is used; pass ``autoescape=False`` only when the output is
+    known to target a non-HTML format.
+    """
     if use_jinja:
-        rendered = _render_with_jinja(template, context)
+        rendered = _render_with_jinja(template, context, autoescape=autoescape)
         if rendered is not None:
             return rendered
     return _render_with_stdlib(template, context)
@@ -30,11 +41,15 @@ def render_file(
     output_path: str | os.PathLike[str] | None = None,
     *,
     use_jinja: bool | None = None,
+    autoescape: bool | None = None,
 ) -> str:
     """Read a template file, render it, optionally write the result.
 
     ``use_jinja=None`` auto-detects: ``.j2`` / ``.jinja`` / ``.jinja2`` suffixes
     opt in to Jinja2; other extensions use :class:`string.Template`.
+
+    ``autoescape=None`` auto-detects based on the output path suffix — HTML /
+    XML targets enable escaping, others disable it. Pass a bool to override.
     """
     src = Path(template_path)
     if not src.is_file():
@@ -44,25 +59,45 @@ def render_file(
     except OSError as error:
         raise TemplateException(f"cannot read template {src}: {error}") from error
     jinja = _wants_jinja(src) if use_jinja is None else use_jinja
-    rendered = render_string(source, context, use_jinja=jinja)
+    escape = _wants_autoescape(output_path, src) if autoescape is None else autoescape
+    rendered = render_string(source, context, use_jinja=jinja, autoescape=escape)
     if output_path is not None:
         dest = Path(output_path)
         dest.parent.mkdir(parents=True, exist_ok=True)
         dest.write_text(rendered, encoding="utf-8")
     return rendered
 
 
+_HTML_SUFFIXES = frozenset({".html", ".htm", ".xhtml", ".xml"})
+
+
 def _wants_jinja(path: Path) -> bool:
     return path.suffix.lower() in {".j2", ".jinja", ".jinja2"}
 
 
-def _render_with_jinja(template: str, context: dict[str, Any]) -> str | None:
+def _wants_autoescape(
+    output_path: str | os.PathLike[str] | None,
+    template_path: Path,
+) -> bool:
+    target = Path(output_path) if output_path is not None else template_path
+    suffix = target.suffix.lower()
+    if suffix in {".j2", ".jinja", ".jinja2"}:
+        suffix = target.with_suffix("").suffix.lower()
+    return suffix in _HTML_SUFFIXES
+
+
+def _render_with_jinja(
+    template: str,
+    context: dict[str, Any],
+    *,
+    autoescape: bool,
+) -> str | None:
     try:
         from jinja2 import Environment, StrictUndefined
         from jinja2 import TemplateError as JinjaTemplateError
     except ImportError:
         return None
-    env = Environment(autoescape=False, undefined=StrictUndefined)
+    env = Environment(autoescape=autoescape, undefined=StrictUndefined)
     try:
         return env.from_string(template).render(**context)
     except JinjaTemplateError as error:

automation_file/server/_websocket.py

@@ -20,8 +20,18 @@
 
 
 def compute_accept_key(sec_websocket_key: str) -> str:
-    """Return the ``Sec-WebSocket-Accept`` value for ``sec_websocket_key``."""
-    digest = hashlib.sha1((sec_websocket_key + _GUID).encode("ascii")).digest()
+    """Return the ``Sec-WebSocket-Accept`` value for ``sec_websocket_key``.
+
+    RFC 6455 mandates SHA-1 + a fixed GUID for the opening handshake — the
+    digest only proves the server understood the handshake, it is not a
+    security primitive. ``usedforsecurity=False`` tells static analysers to
+    skip the standard SHA-1 "insecure hash" warning.
+    """
+    # nosec B303 B324 - RFC 6455 handshake, not a security primitive.
+    digest = hashlib.sha1(
+        (sec_websocket_key + _GUID).encode("ascii"),
+        usedforsecurity=False,
+    ).digest()
     return base64.b64encode(digest).decode("ascii")
 
 

tests/test_templates.py

@@ -12,7 +12,7 @@
 
 def _has_jinja() -> bool:
     try:
-        import jinja2  # noqa: F401
+        import jinja2  # noqa: F401  # pylint: disable=import-outside-toplevel,unused-import
     except ImportError:
         return False
     return True
@@ -64,3 +64,28 @@ def test_render_file_auto_detects_jinja_by_suffix(tmp_path: Path) -> None:
     tmpl = tmp_path / "page.j2"
     tmpl.write_text("{% for v in values %}{{ v }};{% endfor %}", encoding="utf-8")
     assert render_file(tmpl, {"values": [1, 2, 3]}) == "1;2;3;"
+
+
+@pytest.mark.skipif(not _has_jinja(), reason="jinja2 not installed")
+def test_render_string_jinja_autoescapes_html_by_default() -> None:
+    assert render_string("{{ x }}", {"x": "<script>"}) == "&lt;script&gt;"
+
+
+@pytest.mark.skipif(not _has_jinja(), reason="jinja2 not installed")
+def test_render_string_jinja_autoescape_opt_out() -> None:
+    assert render_string("{{ x }}", {"x": "<script>"}, autoescape=False) == "<script>"
+
+
+@pytest.mark.skipif(not _has_jinja(), reason="jinja2 not installed")
+def test_render_file_autoescapes_when_output_is_html(tmp_path: Path) -> None:
+    tmpl = tmp_path / "page.html.j2"
+    tmpl.write_text("{{ x }}", encoding="utf-8")
+    out = tmp_path / "page.html"
+    assert render_file(tmpl, {"x": "<b>"}, out) == "&lt;b&gt;"
+
+
+@pytest.mark.skipif(not _has_jinja(), reason="jinja2 not installed")
+def test_render_file_skips_autoescape_for_non_html(tmp_path: Path) -> None:
+    tmpl = tmp_path / "note.txt"
+    tmpl.write_text("{{ x }}", encoding="utf-8")
+    assert render_file(tmpl, {"x": "<b>"}, use_jinja=True) == "<b>"