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

{mkdocs_easylinks_plugin-0.2.0 → mkdocs_easylinks_plugin-0.2.2}/.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.0 → mkdocs_easylinks_plugin-0.2.2}/.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.0 → mkdocs_easylinks_plugin-0.2.2}/CHANGELOG.md

@@ -2,6 +2,27 @@
 
 All notable changes to this project will be documented in this file.
 
+## [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
+- Replaced deprecated `license = {text = "MIT"}` with SPDX expression `license = "MIT"`
+- Removed deprecated `License :: OSI Approved :: MIT License` classifier
+- Bumped setuptools build requirement to `>=77.0.0` to support SPDX license format
+
 ## [0.2.0] - 2026-04-02
 
 ### Removed

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

@@ -1,16 +1,15 @@
 Metadata-Version: 2.4
 Name: mkdocs-easylinks-plugin
-Version: 0.2.0
+Version: 0.2.2
 Summary: An MkDocs plugin that allows linking to files by filename only
 Author: Daniel Ferguson
-License: MIT
+License-Expression: MIT
 Project-URL: Homepage, https://github.com/dsferg/mkdocs-easylinks-plugin
 Project-URL: Documentation, https://github.com/dsferg/mkdocs-easylinks-plugin
 Project-URL: Repository, https://github.com/dsferg/mkdocs-easylinks-plugin
 Keywords: mkdocs,plugin,links,cross-references
 Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Developers
-Classifier: License :: OSI Approved :: MIT License
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11

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

@@ -17,6 +17,11 @@ from mkdocs.config.defaults import MkDocsConfig
 logger = logging.getLogger("mkdocs.plugins.easylinks")
 
 
+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")
+
+
 class EasyLinksConfig(Config):
     warn_on_missing = config_options.Type(bool, default=True)
     warn_on_ambiguous = config_options.Type(bool, default=True)
@@ -61,12 +66,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 +113,29 @@ 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``).
+        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.
+        """
+        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 +159,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 +193,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 +280,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.0 → mkdocs_easylinks_plugin-0.2.2}/mkdocs_easylinks_plugin.egg-info/PKG-INFO

@@ -1,16 +1,15 @@
 Metadata-Version: 2.4
 Name: mkdocs-easylinks-plugin
-Version: 0.2.0
+Version: 0.2.2
 Summary: An MkDocs plugin that allows linking to files by filename only
 Author: Daniel Ferguson
-License: MIT
+License-Expression: MIT
 Project-URL: Homepage, https://github.com/dsferg/mkdocs-easylinks-plugin
 Project-URL: Documentation, https://github.com/dsferg/mkdocs-easylinks-plugin
 Project-URL: Repository, https://github.com/dsferg/mkdocs-easylinks-plugin
 Keywords: mkdocs,plugin,links,cross-references
 Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Developers
-Classifier: License :: OSI Approved :: MIT License
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11

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

@@ -1,14 +1,14 @@
 [build-system]
-requires = ["setuptools>=45", "wheel", "setuptools_scm[toml]>=6.2"]
+requires = ["setuptools>=77.0.0", "wheel", "setuptools_scm[toml]>=6.2"]
 build-backend = "setuptools.build_meta"
 
 [project]
 name = "mkdocs-easylinks-plugin"
-version = "0.2.0"
+version = "0.2.2"
 description = "An MkDocs plugin that allows linking to files by filename only"
 readme = "README.md"
 requires-python = ">=3.10"
-license = {text = "MIT"}
+license = "MIT"
 authors = [
     {name = "Daniel Ferguson"}
 ]
@@ -16,7 +16,6 @@ keywords = ["mkdocs", "plugin", "links", "cross-references"]
 classifiers = [
     "Development Status :: 4 - Beta",
     "Intended Audience :: Developers",
-    "License :: OSI Approved :: MIT License",
     "Programming Language :: Python :: 3",
     "Programming Language :: Python :: 3.10",
     "Programming Language :: Python :: 3.11",

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

@@ -1152,3 +1152,127 @@ 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"
+
+    # ------------------------------------------------------------------
+    # 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_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