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

{mkdocs_easylinks_plugin-0.2.1 → mkdocs_easylinks_plugin-0.2.3}/.github/workflows/publish.yml

@@ -11,6 +11,9 @@ env:
 jobs:
   publish:
     runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
 
     steps:
       - uses: actions/checkout@v4
@@ -20,14 +23,8 @@ jobs:
         with:
           python-version: "3.12"
 
-      - name: Install build tools
-        run: pip install build twine
-
       - name: Build package
-        run: python -m build
+        run: pip install build && python -m build
 
       - name: Publish to PyPI
-        env:
-          TWINE_USERNAME: __token__
-          TWINE_PASSWORD: ${{ secrets.PYPI_API_TOKEN }}
-        run: twine upload dist/*
+        uses: pypa/gh-action-pypi-publish@release/v1

{mkdocs_easylinks_plugin-0.2.1 → mkdocs_easylinks_plugin-0.2.3}/.gitignore

@@ -42,3 +42,7 @@ ENV/
 # OS
 .DS_Store
 Thumbs.db
+
+# Local Docker testing (not for remote repo)
+Dockerfile
+requirements.txt

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

@@ -2,6 +2,29 @@
 
 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
+- Fixed log injection via user-controlled filenames
+- Fixed path traversal via malformed file paths
+- Fixed URL scheme bypass allowing dangerous link types
+- Fixed misconfigured `exclude_dirs` empty-string entry
+
+### Performance
+- `_restore_protected_blocks` now uses a single compiled regex substitution instead of N sequential `str.replace` calls, making restoration O(n) in document length
+- `_is_safe_path` short-circuits immediately for paths containing no `..` component (the common case), avoiding the `os.path.normpath` call entirely
+- Config flags and the stats dict are captured as locals before the per-link closure is entered, removing repeated attribute and dict lookups on every link match
+- Relative path results are cached per page so repeated links to the same target file call `_get_relative_path` only once
+
 ## [0.2.1] - 2026-04-02
 
 ### Fixed

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mkdocs-easylinks-plugin
-Version: 0.2.1
+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.1 → mkdocs_easylinks_plugin-0.2.3}/mkdocs_easylinks/plugin.py

@@ -17,6 +17,30 @@ 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:
+    """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):
     warn_on_missing = config_options.Type(bool, default=True)
     warn_on_ambiguous = config_options.Type(bool, default=True)
@@ -61,12 +85,24 @@ class EasyLinksPlugin(BasePlugin[EasyLinksConfig]):
         self.stats = {key: 0 for key in self.stats}
         self.link_counts = defaultdict(int)
         self._normalized_exclude_dirs = [
-            d.replace("\\", "/").rstrip("/") + "/" for d in self.config["exclude_dirs"]
+            d.replace("\\", "/").rstrip("/") + "/"
+            for d in self.config["exclude_dirs"]
+            if d  # skip empty strings — they would normalize to "/" and exclude everything
         ]
 
         # Process all files (documentation pages, images, etc.)
         for file in files:
             self.stats["total_files_scanned"] += 1
+
+            # Reject paths that escape the docs root (e.g. via symlink traversal)
+            if not self._is_safe_path(file.src_path):
+                logger.warning(
+                    f"easylinks: Skipping file with path outside docs root: "
+                    f"'{_sanitize_log(file.src_path)}'"
+                )
+                self.stats["files_ignored"] += 1
+                continue
+
             filename = os.path.basename(file.src_path)
 
             # Ignore files starting with a dot (hidden files)
@@ -96,15 +132,35 @@ class EasyLinksPlugin(BasePlugin[EasyLinksConfig]):
         # Warn about ambiguous files
         if self.config["warn_on_ambiguous"] and self.ambiguous_files:
             for filename, paths in self.ambiguous_files.items():
+                safe_filename = _sanitize_log(filename)
+                safe_paths = [_sanitize_log(p) for p in paths]
                 logger.warning(
-                    f"easylinks: Ambiguous filename '{filename}' found in multiple locations:\n"
-                    + "\n".join(f"  - {path}" for path in paths)
+                    f"easylinks: Ambiguous filename '{safe_filename}' found in multiple locations:\n"
+                    + "\n".join(f"  - {p}" for p in safe_paths)
                     + "\nLinks to this file will use the first occurrence. "
                     "Consider using full paths for disambiguation."
                 )
 
         return files
 
+    def _is_safe_path(self, src_path: str) -> bool:
+        """Return True if src_path stays within the docs root.
+
+        MkDocs supplies src_path as a relative path (e.g. ``subdir/page.md``).
+        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("..")
+
     def _is_excluded_dir(self, file_path: str) -> bool:
         """Check if a file is in an excluded directory."""
         if not self._normalized_exclude_dirs:
@@ -128,14 +184,28 @@ class EasyLinksPlugin(BasePlugin[EasyLinksConfig]):
         # Extract code fences and HTML comments before processing
         markdown, protected_blocks = self._extract_protected_blocks(markdown)
 
+        # Capture config flags and stats dict as locals to avoid repeated
+        # attribute + dict lookups inside the closure on every link match.
+        warn_on_ambiguous = self.config["warn_on_ambiguous"]
+        warn_on_missing = self.config["warn_on_missing"]
+        stats = self.stats
+        page_src_path = page.file.src_path
+        # Cache relative-path results within this page: from_path is constant,
+        # so keying on to_path alone is sufficient.
+        relative_path_cache: Dict[str, str] = {}
+
         def replace_link(match):
             is_image = match.group(1)  # Will be '!' for images, None for regular links
             link_text = match.group(2)
             link_url = match.group(3)
 
-            # Skip if it's an external link, anchor, or absolute path
+            # Skip external links, anchors, absolute paths, and any URL with a
+            # scheme (colon present). Using a colon as the scheme sentinel is an
+            # intentional allowlist: bare filenames never contain colons, so any
+            # URL that does (http:, https:, javascript:, data:, file:, mailto:,
+            # blob:, vbscript:, etc.) is left untouched rather than resolved.
             if (link_url.startswith(('http://', 'https://', '//', '#', '/'))
-                    or (':' in link_url and not link_url.startswith('file:'))):
+                    or ':' in link_url):
                 return match.group(0)
 
             # Extract anchor if present (only relevant for links, not images)
@@ -148,45 +218,51 @@ class EasyLinksPlugin(BasePlugin[EasyLinksConfig]):
             if "/" not in link_url and "\\" not in link_url:
                 # Track statistics
                 if is_image:
-                    self.stats["images_processed"] += 1
+                    stats["images_processed"] += 1
                 else:
-                    self.stats["links_processed"] += 1
+                    stats["links_processed"] += 1
 
                 resolved_path = self._resolve_filename(link_url)
                 if resolved_path:
                     # Warn if this filename is ambiguous
-                    if self.config["warn_on_ambiguous"] and link_url in self.ambiguous_files:
+                    if warn_on_ambiguous and link_url in self.ambiguous_files:
                         all_paths = self.ambiguous_files[link_url]
                         logger.warning(
-                            f"easylinks: Ambiguous filename '{link_url}' referred to in "
-                            f"'{page.file.src_path}': exists at {all_paths}. "
-                            f"Using '{resolved_path}'."
+                            f"easylinks: Ambiguous filename '{_sanitize_log(link_url)}' referred to in "
+                            f"'{_sanitize_log(page_src_path)}': exists at "
+                            f"{[_sanitize_log(p) for p in all_paths]}. "
+                            f"Using '{_sanitize_log(resolved_path)}'."
                         )
 
                     # Track successful resolution
                     if is_image:
-                        self.stats["images_resolved"] += 1
+                        stats["images_resolved"] += 1
                     else:
-                        self.stats["links_resolved"] += 1
+                        stats["links_resolved"] += 1
                         # Count how many times each file is linked
                         self.link_counts[resolved_path] += 1
 
-                    # Calculate relative path from current page to target
-                    relative_path = self._get_relative_path(page.file.src_path, resolved_path)
+                    # Calculate relative path from current page to target; cache
+                    # the result since from_path is constant for this page.
+                    if resolved_path not in relative_path_cache:
+                        relative_path_cache[resolved_path] = self._get_relative_path(
+                            page_src_path, resolved_path
+                        )
+                    relative_path = relative_path_cache[resolved_path]
                     # Reconstruct with or without the ! prefix
                     prefix = "!" if is_image else ""
                     return f"{prefix}[{link_text}]({relative_path}{anchor})"
                 else:
                     # Track unresolved links/images separately
                     if is_image:
-                        self.stats["images_unresolved"] += 1
+                        stats["images_unresolved"] += 1
                     else:
-                        self.stats["links_unresolved"] += 1
+                        stats["links_unresolved"] += 1
 
-                    if self.config["warn_on_missing"]:
+                    if warn_on_missing:
                         file_type = "image" if is_image else "file"
                         logger.warning(
-                            f"easylinks: Could not resolve {file_type} link to '{link_url}' on page '{page.file.src_path}'"
+                            f"easylinks: Could not resolve {file_type} link to '{_sanitize_log(link_url)}' on page '{_sanitize_log(page_src_path)}'"
                         )
 
             return match.group(0)
@@ -229,9 +305,10 @@ class EasyLinksPlugin(BasePlugin[EasyLinksConfig]):
 
     def _restore_protected_blocks(self, markdown: str, protected_blocks: dict) -> str:
         """Restore protected blocks from placeholders."""
-        for placeholder, original in protected_blocks.items():
-            markdown = markdown.replace(placeholder, original)
-        return markdown
+        if not protected_blocks:
+            return markdown
+        pattern = re.compile('|'.join(re.escape(k) for k in protected_blocks))
+        return pattern.sub(lambda m: protected_blocks[m.group(0)], markdown)
 
     def _resolve_filename(self, filename: str) -> Optional[str]:
         """Resolve a filename to its full path within the docs."""

{mkdocs_easylinks_plugin-0.2.1 → 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.1
+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.1 → 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.1"
+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.1 → mkdocs_easylinks_plugin-0.2.3}/tests/test_plugin.py

@@ -1152,3 +1152,165 @@ Regular paragraph with [example link](example.md).
 
         # Image in admonition should be processed
         assert "../images/diagram.png" in result
+
+    # ------------------------------------------------------------------
+    # Security fix: log injection (_sanitize_log)
+    # ------------------------------------------------------------------
+
+    def test_sanitize_log_escapes_newlines(self):
+        """_sanitize_log must escape newlines so they cannot inject fake log lines."""
+        from mkdocs_easylinks.plugin import _sanitize_log
+        assert _sanitize_log("file\nINJECTED WARNING.md") == "file\\nINJECTED WARNING.md"
+
+    def test_sanitize_log_escapes_carriage_returns(self):
+        """_sanitize_log must escape carriage returns."""
+        from mkdocs_easylinks.plugin import _sanitize_log
+        assert _sanitize_log("file\r.md") == "file\\r.md"
+
+    def test_sanitize_log_escapes_tabs(self):
+        """_sanitize_log must escape tab characters."""
+        from mkdocs_easylinks.plugin import _sanitize_log
+        assert _sanitize_log("file\t.md") == "file\\t.md"
+
+    def test_sanitize_log_normal_string_unchanged(self):
+        """_sanitize_log must leave strings without control characters unchanged."""
+        from mkdocs_easylinks.plugin import _sanitize_log
+        assert _sanitize_log("subdir/normal-file.md") == "subdir/normal-file.md"
+
+    def test_sanitize_log_multiple_control_chars(self):
+        """_sanitize_log must escape all control character types in one pass."""
+        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)
+    # ------------------------------------------------------------------
+
+    def test_is_safe_path_normal_path(self):
+        """A normal relative path should be considered safe."""
+        assert self.plugin._is_safe_path("subdir/file.md") is True
+
+    def test_is_safe_path_root_level_file(self):
+        """A filename at the root level should be safe."""
+        assert self.plugin._is_safe_path("file.md") is True
+
+    def test_is_safe_path_traversal_escape(self):
+        """A path that escapes the docs root must be rejected."""
+        assert self.plugin._is_safe_path("../../etc/passwd") is False
+
+    def test_is_safe_path_single_parent_traversal(self):
+        """A path starting with .. must be rejected."""
+        assert self.plugin._is_safe_path("../outside.md") is False
+
+    def test_is_safe_path_embedded_traversal_that_escapes(self):
+        """An embedded .. sequence that resolves outside the root must be rejected."""
+        assert self.plugin._is_safe_path("subdir/../../../escape.md") is False
+
+    def test_is_safe_path_embedded_traversal_that_stays_inside(self):
+        """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()
+        mock_files = MagicMock(spec=Files)
+
+        safe_file = self.create_mock_file("docs/safe.md")
+        traversal_file = self.create_mock_file("../../secret.md")
+
+        mock_files.__iter__ = MagicMock(return_value=iter([safe_file, traversal_file]))
+
+        self.plugin.on_files(mock_files, config=mock_config)
+
+        assert "safe.md" in self.plugin.file_map
+        assert "secret.md" not in self.plugin.file_map
+        assert self.plugin.stats["files_ignored"] == 1
+
+    # ------------------------------------------------------------------
+    # Security fix: URL scheme allowlist
+    # ------------------------------------------------------------------
+
+    def test_dangerous_url_schemes_unchanged(self):
+        """Links with dangerous URL schemes must be returned untouched."""
+        page = self.create_mock_page("docs/index.md")
+
+        dangerous = [
+            "[XSS](javascript:alert(1))",
+            "[Data](data:text/html,<h1>test</h1>)",
+            "[VB](vbscript:msgbox('xss'))",
+            "[Blob](blob:https://example.com/some-uuid)",
+        ]
+
+        for markdown in dangerous:
+            result = self.plugin._process_links(markdown, page)
+            assert result == markdown, f"Expected unchanged: {markdown}"
+
+    def test_file_url_unchanged(self):
+        """file: URLs must be passed through unchanged, not treated as filenames."""
+        # Even if a matching basename happened to be indexed, the scheme must win.
+        self.plugin.file_map = {"passwd": "/etc/passwd"}
+        page = self.create_mock_page("docs/index.md")
+        markdown = "[Secret](file:///etc/passwd)"
+
+        result = self.plugin._process_links(markdown, page)
+        assert result == markdown
+
+    # ------------------------------------------------------------------
+    # Security fix: empty string in exclude_dirs
+    # ------------------------------------------------------------------
+
+    def test_exclude_dirs_empty_string_does_not_exclude_all(self):
+        """An empty string entry in exclude_dirs must not silently exclude every file."""
+        self.plugin.config["exclude_dirs"] = [""]
+
+        mock_config = MagicMock()
+        mock_files = MagicMock(spec=Files)
+
+        file1 = self.create_mock_file("docs/page.md")
+        file2 = self.create_mock_file("docs/another.md")
+
+        mock_files.__iter__ = MagicMock(return_value=iter([file1, file2]))
+
+        self.plugin.on_files(mock_files, config=mock_config)
+
+        assert "page.md" in self.plugin.file_map
+        assert "another.md" in self.plugin.file_map
+        assert self.plugin.stats["files_indexed"] == 2

mkdocs_easylinks_plugin-0.2.1/mkdocs_easylinks/__init__.py

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