mkdocs-easylinks-plugin 0.2.2__tar.gz → 0.2.3__tar.gz

{mkdocs_easylinks_plugin-0.2.2 → mkdocs_easylinks_plugin-0.2.3}/CHANGELOG.md

@@ -2,6 +2,15 @@
 
 All notable changes to this project will be documented in this file.
 
+## [0.2.3] - 2026-04-29
+
+### Security
+- Expanded log sanitizer to escape ANSI escape sequences, NUL bytes, vertical tab, form feed, and Unicode line separators (U+2028/U+2029) in addition to `\n`, `\r`, and `\t`
+- Path safety check now rejects absolute and drive-relative paths (e.g. `/etc/passwd`, `C:\…`, `\\server\share\…`) in addition to `..` traversal
+
+### Fixed
+- `mkdocs_easylinks.__version__` is now read from installed package metadata, eliminating drift between `pyproject.toml` and the module attribute
+
 ## [0.2.2] - 2026-04-13
 
 ### Security

{mkdocs_easylinks_plugin-0.2.2 → mkdocs_easylinks_plugin-0.2.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mkdocs-easylinks-plugin
-Version: 0.2.2
+Version: 0.2.3
 Summary: An MkDocs plugin that allows linking to files by filename only
 Author: Daniel Ferguson
 License-Expression: MIT

mkdocs_easylinks_plugin-0.2.3/mkdocs_easylinks/__init__.py

@@ -0,0 +1,8 @@
+"""MkDocs EasyLinks Plugin - Simplified cross-referencing by filename."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("mkdocs-easylinks-plugin")
+except PackageNotFoundError:  # pragma: no cover
+    __version__ = "unknown"

{mkdocs_easylinks_plugin-0.2.2 → mkdocs_easylinks_plugin-0.2.3}/mkdocs_easylinks/plugin.py

@@ -17,9 +17,28 @@ from mkdocs.config.defaults import MkDocsConfig
 logger = logging.getLogger("mkdocs.plugins.easylinks")
 
 
+_LOG_ESCAPES = {"\n": "\\n", "\r": "\\r", "\t": "\\t"}
+
+
 def _sanitize_log(value: str) -> str:
-    """Strip control characters from user-controlled strings before logging."""
-    return value.replace("\n", "\\n").replace("\r", "\\r").replace("\t", "\\t")
+    """Escape control characters and other non-printable codepoints before logging.
+
+    Filenames can legally contain ANSI escape sequences, NULs, vertical tabs,
+    form feeds, or Unicode line separators on POSIX systems. Logging them
+    verbatim would let an attacker spoof log lines, recolor output, or
+    manipulate a terminal that tails the build log.
+    """
+    out = []
+    for c in value:
+        if c in _LOG_ESCAPES:
+            out.append(_LOG_ESCAPES[c])
+        elif c.isprintable():
+            out.append(c)
+        elif ord(c) <= 0xff:
+            out.append(f"\\x{ord(c):02x}")
+        else:
+            out.append(f"\\u{ord(c):04x}")
+    return "".join(out)
 
 
 class EasyLinksConfig(Config):
@@ -128,10 +147,16 @@ class EasyLinksPlugin(BasePlugin[EasyLinksConfig]):
         """Return True if src_path stays within the docs root.
 
         MkDocs supplies src_path as a relative path (e.g. ``subdir/page.md``).
-        A path that escapes the docs root after normalization (e.g.
-        ``../../etc/passwd``) would produce a traversal link in the output and
-        must be rejected.
+        Absolute paths (``/etc/passwd``, ``C:\\Windows\\...``, UNC paths) and
+        relative paths that escape the docs root after normalization (e.g.
+        ``../../etc/passwd``) would both produce traversal links in the
+        output and must be rejected.
         """
+        # os.path.isabs alone is not enough: on Python 3.13+ Windows it returns
+        # False for drive-relative paths like ``/etc/passwd`` or ``\foo``, which
+        # would still escape the docs root once a drive is resolved.
+        if os.path.isabs(src_path) or src_path.startswith(("/", "\\")):
+            return False
         if ".." not in src_path:
             return True
         return not os.path.normpath(src_path).startswith("..")

{mkdocs_easylinks_plugin-0.2.2 → mkdocs_easylinks_plugin-0.2.3}/mkdocs_easylinks_plugin.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mkdocs-easylinks-plugin
-Version: 0.2.2
+Version: 0.2.3
 Summary: An MkDocs plugin that allows linking to files by filename only
 Author: Daniel Ferguson
 License-Expression: MIT

{mkdocs_easylinks_plugin-0.2.2 → mkdocs_easylinks_plugin-0.2.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "mkdocs-easylinks-plugin"
-version = "0.2.2"
+version = "0.2.3"
 description = "An MkDocs plugin that allows linking to files by filename only"
 readme = "README.md"
 requires-python = ">=3.10"

{mkdocs_easylinks_plugin-0.2.2 → mkdocs_easylinks_plugin-0.2.3}/tests/test_plugin.py

@@ -1182,6 +1182,31 @@ Regular paragraph with [example link](example.md).
         from mkdocs_easylinks.plugin import _sanitize_log
         assert _sanitize_log("a\nb\rc\td") == "a\\nb\\rc\\td"
 
+    def test_sanitize_log_escapes_ansi_escape(self):
+        """_sanitize_log must escape ESC so terminals tailing logs cannot be hijacked."""
+        from mkdocs_easylinks.plugin import _sanitize_log
+        assert _sanitize_log("file\x1b[31mRED.md") == "file\\x1b[31mRED.md"
+
+    def test_sanitize_log_escapes_null_byte(self):
+        """_sanitize_log must escape NUL bytes."""
+        from mkdocs_easylinks.plugin import _sanitize_log
+        assert _sanitize_log("file\x00.md") == "file\\x00.md"
+
+    def test_sanitize_log_escapes_vertical_tab_and_form_feed(self):
+        """_sanitize_log must escape \\v and \\f, which can move the cursor in some terminals."""
+        from mkdocs_easylinks.plugin import _sanitize_log
+        assert _sanitize_log("a\vb\fc") == "a\\x0bb\\x0cc"
+
+    def test_sanitize_log_escapes_unicode_line_separator(self):
+        """_sanitize_log must escape U+2028 and U+2029, which act as line breaks in some viewers."""
+        from mkdocs_easylinks.plugin import _sanitize_log
+        assert _sanitize_log("a
b
c") == "a\\u2028b\\u2029c"
+
+    def test_sanitize_log_preserves_printable_unicode(self):
+        """_sanitize_log must leave printable Unicode (accents, emoji, CJK) alone."""
+        from mkdocs_easylinks.plugin import _sanitize_log
+        assert _sanitize_log("café-日本語-🚀.md") == "café-日本語-🚀.md"
+
     # ------------------------------------------------------------------
     # Security fix: path traversal (_is_safe_path / on_files)
     # ------------------------------------------------------------------
@@ -1210,6 +1235,19 @@ Regular paragraph with [example link](example.md).
         """An embedded .. that stays within the root should be accepted."""
         assert self.plugin._is_safe_path("subdir/../other/file.md") is True
 
+    def test_is_safe_path_rejects_posix_absolute(self):
+        """An absolute POSIX path must be rejected even though it has no '..'."""
+        assert self.plugin._is_safe_path("/etc/passwd") is False
+
+    def test_is_safe_path_rejects_windows_absolute(self):
+        """An absolute Windows path must be rejected when running on Windows."""
+        import os
+        import pytest
+        if os.name != "nt":
+            pytest.skip("Windows-specific path semantics")
+        assert self.plugin._is_safe_path(r"C:\Windows\System32\config\SAM") is False
+        assert self.plugin._is_safe_path(r"\\server\share\file.md") is False
+
     def test_traversal_path_ignored_in_on_files(self):
         """Files whose src_path escapes the docs root must be excluded from the index."""
         mock_config = MagicMock()

mkdocs_easylinks_plugin-0.2.2/mkdocs_easylinks/__init__.py

@@ -1,3 +0,0 @@
-"""MkDocs EasyLinks Plugin - Simplified cross-referencing by filename."""
-
-__version__ = "0.1.4"