[FEATURE] Added inital implementation of url sanitization to documentation config (- WIP #213 -)

Changes in file docs/conf.py:
  * integrate the url sanitation functions

Changes in file docs/utils.py:
  * implemented the url sanitation functions
  * related work

Author: reactive-firewall

docs/conf.py

@@ -46,6 +46,8 @@
 sys.path.insert(0, os.path.abspath(".."))
 from docs.utils import _validate_git_ref  # noqa
 from docs.utils import slugify_header  # noqa
+from docs.utils import sanitize_url  # noqa
+from docs.utils import sanitize_intersphinx_mapping  # noqa
 
 # Define the branch reference for linkcode_resolve
 DOCS_BUILD_REF: str = _validate_git_ref(os.environ.get("DOCS_BUILD_REF", "stable"))
@@ -309,7 +311,7 @@
 myst_gfm_only = False
 
 myst_html_meta = {
-	"github_url": f"https://github.com/reactive-firewall/{project}"
+	"github_url": sanitize_url(f"https://github.com/reactive-firewall/{project}")
 }
 
 # For GH-style admonitions to MyST conversion
@@ -419,7 +421,7 @@
 
 # -- Link resolver -------------------------------------------------------------
 
-linkcode_url_prefix: str = f"https://github.com/reactive-firewall/{project}"
+linkcode_url_prefix: str = sanitize_url(f"https://github.com/reactive-firewall/{project}")
 
 suffix = "/issues/%s"
 
@@ -432,9 +434,11 @@
 
 # try to link with official python3 documentation.
 # see https://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html for more
-intersphinx_mapping = {
-	"python": ("https://docs.python.org/3", (None, "python-inv.txt"))
-}
+intersphinx_mapping = sanitize_intersphinx_mapping(
+	{
+		"python": ("https://docs.python.org/3", (None, "python-inv.txt")),
+	},
+)
 
 
 def linkcode_resolve(domain, info):
@@ -450,4 +454,4 @@ def linkcode_resolve(domain, info):
 		theResult = theResult.replace("/multicast.py", "/multicast/__init__.py")
 	if "/tests.py" in theResult:
 		theResult = theResult.replace("/tests.py", "/tests/__init__.py")
-	return quote(theResult, safe=":/-._")
+	return sanitize_url(quote(theResult, safe=":/-._"))

docs/utils.py

@@ -17,6 +17,7 @@
 # limitations under the License.
 
 import re
+from urllib.parse import urlparse, urlunparse, quote
 
 
 # Git reference validation pattern
@@ -26,6 +27,18 @@
 GIT_REF_PATTERN = r'^[a-zA-Z0-9][a-zA-Z0-9_\-./]*$'
 
 
+# URL allowed scheme list
+# Enforces:
+# - URLs Must start with https
+URL_ALLOWED_SCHEMES = {"https"}
+
+
+# URL allowed domain list
+# Enforces:
+# - URLs Must belone to one of these domains
+URL_ALLOWED_NETLOCS = {"github.com", "readthedocs.com"}
+
+
 def _validate_git_ref(ref: str) -> str:
 	"""
 	Validate if the provided string is a valid Git reference.
@@ -126,3 +139,34 @@ def slugify_header(s: str) -> str:
 	text = re.sub(r'[^\w\- ]', "", s).strip().lower()
 	# Then replace consecutive spaces or dashes with a single dash
 	return re.sub(r'[-\s]+', "-", text)
+
+
+def sanitize_url(url):
+	"""ADD DOCS.
+	"""
+	parsed_url = urlparse(url)
+	# Validate scheme
+	if parsed_url.scheme not in URL_ALLOWED_SCHEMES:
+		raise ValueError("Invalid URL scheme. Only 'https' is allowed.")
+	# Validate netloc
+	if parsed_url.netloc not in URL_ALLOWED_NETLOCS:
+		raise ValueError(f"Invalid or untrusted domain. Only {URL_ALLOWED_NETLOCS} are allowed.")
+	# Sanitize path and query
+	sanitized_path = quote(parsed_url.path)
+	sanitized_query = quote(parsed_url.query)
+	# Reconstruct the sanitized URL
+	sanitized_url = urlunparse((
+		parsed_url.scheme,
+		parsed_url.netloc,
+		sanitized_path,
+		parsed_url.params,
+		sanitized_query,
+		parsed_url.fragment
+	))
+	return sanitized_url
+
+
+def sanitize_intersphinx_mapping(mapping):
+	"""ADD DOCS.
+	"""
+	return {key: (sanitize_url(url), extra_value) for key, (url, extra_value) in mapping.items()}