cal-docs-server 3.0.0b1__py3-none-any.whl

cal_docs_server/async_file.py

@@ -0,0 +1,112 @@
+# ----------------------------------------------------------------------------------------
+#   async_file
+#   ----------
+#
+#   Provides async file functions
+#
+#   License
+#   -------
+#   MIT License - Copyright 2025-2026 Cyber Assessment Labs
+#
+#   Authors
+#   -------
+#   bena
+#
+#   Version History
+#   ---------------
+#   Mar 2024 - Created
+#   Dec 2025 - New version 2
+# ----------------------------------------------------------------------------------------
+
+# ----------------------------------------------------------------------------------------
+#   Imports
+# ----------------------------------------------------------------------------------------
+
+import asyncio
+import contextlib
+import io
+from typing import TYPE_CHECKING
+from typing import Literal
+from typing import cast
+
+if TYPE_CHECKING:
+    from collections.abc import AsyncGenerator
+
+# ----------------------------------------------------------------------------------------
+#   Functions
+# ----------------------------------------------------------------------------------------
+
+
+# ----------------------------------------------------------------------------------------
+@contextlib.asynccontextmanager
+async def open_binary(
+    file_path: str, mode: BinaryFileMode = "rb"
+) -> AsyncGenerator[BinaryFile]:
+    loop = asyncio.get_running_loop()
+    file = await loop.run_in_executor(None, open, file_path, mode)
+    assert isinstance(file, io.BufferedIOBase)
+
+    # file = await _open_binary(file_path, mode)
+    file_class = BinaryFile(file)
+    try:
+        yield file_class
+    finally:
+        await file_class.close()
+
+
+# ----------------------------------------------------------------------------------------
+@contextlib.asynccontextmanager
+async def open_text(
+    file_path: str, mode: TextFileMode = "rt"
+) -> AsyncGenerator[TextFile]:
+    loop = asyncio.get_running_loop()
+    file = await loop.run_in_executor(None, open, file_path, mode)
+    file_class = TextFile(cast("io.TextIOWrapper", file))
+    try:
+        yield file_class
+    finally:
+        await file_class.close()
+
+
+# ----------------------------------------------------------------------------------------
+#   Classes
+# ----------------------------------------------------------------------------------------
+
+BinaryFileMode = Literal["rb", "wb", "w+b"]
+TextFileMode = Literal["r", "rt", "w", "wt", "w+", "w+t"]
+
+
+# ----------------------------------------------------------------------------------------
+class BinaryFile:
+    def __init__(self, file: io.BufferedIOBase):
+        self.__file = file
+
+    async def read(self, size: int = -1) -> bytes:
+        loop = asyncio.get_running_loop()
+        return await loop.run_in_executor(None, self.__file.read, size)
+
+    async def write(self, data: bytes) -> None:
+        loop = asyncio.get_running_loop()
+        await loop.run_in_executor(None, self.__file.write, data)
+
+    async def close(self) -> None:
+        loop = asyncio.get_running_loop()
+        await loop.run_in_executor(None, self.__file.close)
+
+
+# ----------------------------------------------------------------------------------------
+class TextFile:
+    def __init__(self, file: io.TextIOWrapper):
+        self.__file = file
+
+    async def read(self, size: int = -1) -> str:
+        loop = asyncio.get_running_loop()
+        return await loop.run_in_executor(None, self.__file.read, size)
+
+    async def write(self, data: str) -> None:
+        loop = asyncio.get_running_loop()
+        await loop.run_in_executor(None, self.__file.write, data)
+
+    async def close(self) -> None:
+        loop = asyncio.get_running_loop()
+        await loop.run_in_executor(None, self.__file.close)

cal_docs_server/auth.py

@@ -0,0 +1,253 @@
+# ----------------------------------------------------------------------------------------
+#   auth
+#   ----
+#
+#   Token-based authentication for API endpoints
+#
+#   License
+#   -------
+#   MIT License - Copyright 2025-2026 Cyber Assessment Labs
+#
+#   Authors
+#   -------
+#   bena (via Claude)
+#
+#   Version History
+#   ---------------
+#   Feb 2026 - Created
+# ----------------------------------------------------------------------------------------
+
+# ----------------------------------------------------------------------------------------
+#   Imports
+# ----------------------------------------------------------------------------------------
+
+import json
+import logging
+import time
+from typing import Any
+from typing import TypedDict
+from aiohttp import web
+
+# ----------------------------------------------------------------------------------------
+#   Types
+# ----------------------------------------------------------------------------------------
+
+
+class TokenInfo(TypedDict):
+    """Information about a token's permissions."""
+
+    name: str  # Human-readable token name
+    projects: list[str] | None  # None = all projects allowed
+    allow_overwrite: bool
+    existing_projects_only: bool
+
+
+TokensDict = dict[str, TokenInfo]
+
+# ----------------------------------------------------------------------------------------
+#   Token Cache
+# ----------------------------------------------------------------------------------------
+
+_tokens_cache: TokensDict = {}
+_tokens_cache_time: float = 0.0
+_TOKENS_CACHE_TTL: float = 5.0  # Reload tokens at most every 5 seconds
+
+# ----------------------------------------------------------------------------------------
+#   Functions
+# ----------------------------------------------------------------------------------------
+
+
+# ----------------------------------------------------------------------------------------
+def _json_dumps(data: Any) -> str:
+    """JSON serializer with consistent formatting and trailing newline."""
+    return json.dumps(data, indent=2) + "\n"
+
+
+# ----------------------------------------------------------------------------------------
+def load_tokens(file_path: str | None) -> TokensDict:
+    """
+    Loads authentication tokens from a JSON file.
+    Returns empty dict if file_path is None or on any error (logged).
+
+    Format:
+    {
+        "tokens": {
+            "admin": {
+                "token": "abc123xyz",
+                "allow_overwrite": true
+            },
+            "ci-pipeline": {
+                "token": "def456uvw",
+                "projects": ["my-project"]
+            }
+        }
+    }
+
+    Key is a human-readable name. Fields:
+    - token (required): the actual secret token value
+    - projects (optional): list of allowed projects. Omit for all projects
+    - allow_overwrite (optional): defaults to false. Set true to allow overwrites
+    - existing_projects_only (optional): defaults to false. Set true to only allow
+      uploading new versions to existing projects
+    """
+
+    if file_path is None:
+        return {}
+
+    try:
+        with open(file_path) as f:
+            data: dict[str, dict[str, dict[str, Any]]] = json.load(f)
+    except FileNotFoundError:
+        logging.error("Tokens file not found: %s", file_path)
+        return {}
+    except json.JSONDecodeError as e:
+        logging.error("Invalid JSON in tokens file %s: %s", file_path, e)
+        return {}
+    except PermissionError:
+        logging.error("Permission denied reading tokens file: %s", file_path)
+        return {}
+    except OSError as e:
+        logging.error("Error reading tokens file %s: %s", file_path, e)
+        return {}
+
+    tokens: TokensDict = {}
+    for name, entry in data.get("tokens", {}).items():
+        token_str: str = entry.get("token", "")
+        if token_str:
+            tokens[token_str] = {
+                "name": name,
+                "projects": entry.get("projects"),  # None = all projects
+                "allow_overwrite": entry.get("allow_overwrite", False),
+                "existing_projects_only": entry.get("existing_projects_only", False),
+            }
+
+    return tokens
+
+
+# ----------------------------------------------------------------------------------------
+def get_tokens(request: web.Request) -> TokensDict:
+    """
+    Gets the current tokens, reloading from file if cache has expired.
+    Reloads at most every 5 seconds to avoid excessive file reads.
+    """
+
+    global _tokens_cache, _tokens_cache_time
+
+    tokens_file: str | None = request.app.get("tokens_file")
+    if tokens_file is None:
+        return {}
+
+    now = time.time()
+    if now - _tokens_cache_time >= _TOKENS_CACHE_TTL:
+        _tokens_cache = load_tokens(tokens_file)
+        _tokens_cache_time = now
+        logging.debug("Reloaded tokens from %s", tokens_file)
+
+    return _tokens_cache
+
+
+# ----------------------------------------------------------------------------------------
+def get_token_info(request: web.Request) -> TokenInfo | None:
+    """
+    Gets the TokenInfo for the request's token, or None if invalid/missing.
+    """
+
+    tokens = get_tokens(request)
+
+    if not tokens:
+        return None
+
+    token = request.headers.get("X-Token", "")
+    if token and token in tokens:
+        return tokens[token]
+
+    return None
+
+
+# ----------------------------------------------------------------------------------------
+def check_auth(request: web.Request) -> bool:
+    """
+    Validates the request has a valid authentication token.
+    Checks X-Token header for the token value.
+    Returns True if valid, False otherwise.
+    """
+
+    return get_token_info(request) is not None
+
+
+# ----------------------------------------------------------------------------------------
+def check_project_allowed(request: web.Request, project: str) -> bool:
+    """
+    Checks if the token is allowed to upload to the specified project.
+    Returns False if token is invalid or project not allowed.
+    """
+
+    token_info = get_token_info(request)
+    if token_info is None:
+        return False
+
+    allowed_projects = token_info["projects"]
+    if allowed_projects is None:
+        return True  # No restriction
+
+    return project in allowed_projects
+
+
+# ----------------------------------------------------------------------------------------
+def check_overwrite_allowed(request: web.Request) -> bool:
+    """
+    Checks if the token is allowed to overwrite existing directories.
+    Returns False if token is invalid or overwrite not allowed.
+    """
+
+    token_info = get_token_info(request)
+    if token_info is None:
+        return False
+
+    return token_info["allow_overwrite"]
+
+
+# ----------------------------------------------------------------------------------------
+def check_existing_projects_only(request: web.Request) -> bool:
+    """
+    Checks if the token is restricted to existing projects only.
+    Returns True if token requires existing projects, False otherwise.
+    """
+
+    token_info = get_token_info(request)
+    if token_info is None:
+        return False
+
+    return token_info["existing_projects_only"]
+
+
+# ----------------------------------------------------------------------------------------
+def get_token_name(request: web.Request) -> str | None:
+    """
+    Gets the human-readable name of the token used in the request.
+    Returns None if no valid token.
+    """
+
+    token_info = get_token_info(request)
+    if token_info is None:
+        return None
+
+    return token_info["name"]
+
+
+# ----------------------------------------------------------------------------------------
+def require_auth(request: web.Request) -> web.Response | None:
+    """
+    Helper that returns 401 response if auth fails, None if auth succeeds.
+    Usage:
+        if error := require_auth(request):
+            return error
+    """
+
+    if not check_auth(request):
+        return web.json_response(
+            dumps=_json_dumps,
+            data={"error": "Unauthorized", "message": "Valid API token required"},
+            status=401,
+        )
+    return None

cal_docs_server/cache_render_index.py

@@ -0,0 +1,106 @@
+# ----------------------------------------------------------------------------------------
+#   cache_render_index
+#   ------------------
+#
+#   This caches the index page so it doesn't render it on every request, only if enough
+#   time has passed between previous render.
+#
+#   License
+#   -------
+#   MIT License - Copyright 2025-2026 Cyber Assessment Labs
+#
+#   Authors
+#   -------
+#   bena
+#
+#   Version History
+#   ---------------
+#   Mar 2024 - Created
+#   Dec 2025 - New version 2
+# ----------------------------------------------------------------------------------------
+
+# ----------------------------------------------------------------------------------------
+#   Imports
+# ----------------------------------------------------------------------------------------
+
+import asyncio
+import time
+from . import index_docs
+from . import render_index
+
+# ----------------------------------------------------------------------------------------
+#   Constants
+# ----------------------------------------------------------------------------------------
+
+CACHE_TIME_SECONDS = 20
+
+# ----------------------------------------------------------------------------------------
+#   Globals
+# ----------------------------------------------------------------------------------------
+
+g_last_rendered_html: str = ""
+g_last_rendered_time: float = 0
+g_currently_rendering: bool = False
+g_version_redirects: dict[str, str] = {}
+
+# ----------------------------------------------------------------------------------------
+#   Functions
+# ----------------------------------------------------------------------------------------
+
+
+# ----------------------------------------------------------------------------------------
+async def cache_render_index(
+    root_directory: str, server_name: str = "Documents Server"
+) -> tuple[str, dict[str, str]]:
+    """
+    Builds index from `root_directory` and renders it into HTML. This will cache the
+    result for a certain amount of time and re use it if another request comes in
+    within the time.
+    Returns a tuple of (html, version_redirects dict)
+    """
+
+    global g_last_rendered_time
+    global g_last_rendered_html
+    global g_currently_rendering
+    global g_version_redirects
+
+    if g_currently_rendering:
+        # If already rendering, then just wait for this one to finish and then return
+        # it rather than start another one.
+        await _wait_for_render()
+
+    elif time.time() - g_last_rendered_time > CACHE_TIME_SECONDS:
+        # Been too long so render a new one.
+        g_currently_rendering = True
+
+        # Build the index
+        index_list = await index_docs.make_index(root_directory=root_directory)
+
+        # Get version redirects
+        g_version_redirects = index_docs.get_version_redirects(index_list)
+
+        # Render HTML
+        html = await render_index.render_index_from_list(
+            index_list, server_name=server_name
+        )
+        g_last_rendered_html = html
+        g_currently_rendering = False
+        g_last_rendered_time = time.time()
+
+    else:
+        # Otherwise just use the current cache
+        pass
+
+    return g_last_rendered_html, g_version_redirects
+
+
+# ----------------------------------------------------------------------------------------
+async def _wait_for_render() -> None:
+    """
+    Waits until `g_currently_rendering` is False
+    """
+
+    global g_currently_rendering
+
+    while g_currently_rendering:
+        await asyncio.sleep(0.05)