qodalis-cli-server-plugin-audit 1.0.0b18__tar.gz

qodalis_cli_server_plugin_audit-1.0.0b18/.gitignore

@@ -0,0 +1,44 @@
+# Byte-compiled / optimized
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Distribution / packaging
+*.egg-info/
+dist/
+build/
+.eggs/
+*.egg
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# Environment variables
+.env
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+TestResults/
+
+# Type checking / linting
+.mypy_cache/
+.ruff_cache/
+
+# C extensions
+*.so
+
+# IDEs and editors
+.idea/
+.vscode/*
+!.vscode/settings.json
+!.vscode/launch.json
+!.vscode/extensions.json
+
+# System files
+.DS_Store
+Thumbs.db
+node_modules/

qodalis_cli_server_plugin_audit-1.0.0b18/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024-2026 Qodalis Solutions
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

qodalis_cli_server_plugin_audit-1.0.0b18/PKG-INFO

@@ -0,0 +1,22 @@
+Metadata-Version: 2.5
+Name: qodalis-cli-server-plugin-audit
+Version: 1.0.0b18
+Summary: Audit log plugin for Qodalis CLI servers — who did what, to whom and when, and its API
+Project-URL: Homepage, https://github.com/qodalis-solutions/cli-server-python
+Project-URL: Repository, https://github.com/qodalis-solutions/cli-server-python
+Project-URL: Issues, https://github.com/qodalis-solutions/cli-server-python/issues
+Author-email: Nicolae Lupei <nicolae.lupei@qodalis.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: audit,audit-log,cli,plugin,qodalis
+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
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.10
+Requires-Dist: fastapi>=0.100.0
+Requires-Dist: qodalis-cli-server-abstractions>=1.0.0b17

qodalis_cli_server_plugin_audit-1.0.0b18/pyproject.toml

@@ -0,0 +1,40 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "qodalis-cli-server-plugin-audit"
+version = "1.0.0b18"
+description = "Audit log plugin for Qodalis CLI servers — who did what, to whom and when, and its API"
+readme = { text = "", content-type = "text/plain" }
+license = "MIT"
+requires-python = ">=3.10"
+authors = [
+    { name = "Nicolae Lupei", email = "nicolae.lupei@qodalis.com" },
+]
+keywords = ["cli", "qodalis", "audit", "audit-log", "plugin"]
+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",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+]
+dependencies = [
+    "qodalis-cli-server-abstractions>=1.0.0b17",
+    "fastapi>=0.100.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/qodalis-solutions/cli-server-python"
+Repository = "https://github.com/qodalis-solutions/cli-server-python"
+Issues = "https://github.com/qodalis-solutions/cli-server-python/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["qodalis_cli_audit"]
+
+[tool.hatch.build.targets.sdist]
+include = ["qodalis_cli_audit/**"]

qodalis_cli_server_plugin_audit-1.0.0b18/qodalis_cli_audit/__init__.py

@@ -0,0 +1,48 @@
+"""Qodalis CLI audit plugin — the audit log (who did what, to whom or what,
+and when), its in-memory store and its API at ``/api/v1/qcli/audit``."""
+
+from __future__ import annotations
+
+from qodalis_cli_server_abstractions.audit import (
+    AuditEntry,
+    AuditMetadata,
+    AuditQueryOptions,
+    IAuditStore,
+)
+
+from .cli_audit_builder import PREFIX, CliAuditBuilder, CliAuditPlugin, get_audit_plugin
+from .cli_audit_controller import (
+    AUDIT_CLEAR,
+    AUDIT_CLEARED_EVENT,
+    AUDIT_READ,
+    DEFAULT_AUDIT_LIMIT,
+    MAX_AUDIT_LIMIT,
+    create_audit_router,
+)
+from .in_memory_audit_store import (
+    FAILED_LOGIN_EVENT,
+    MAX_ENTRIES,
+    MAX_FAILED_LOGIN_ENTRIES,
+    InMemoryAuditStore,
+)
+
+__all__ = [
+    "AUDIT_CLEAR",
+    "AUDIT_CLEARED_EVENT",
+    "AUDIT_READ",
+    "AuditEntry",
+    "AuditMetadata",
+    "AuditQueryOptions",
+    "CliAuditBuilder",
+    "CliAuditPlugin",
+    "DEFAULT_AUDIT_LIMIT",
+    "FAILED_LOGIN_EVENT",
+    "IAuditStore",
+    "InMemoryAuditStore",
+    "MAX_AUDIT_LIMIT",
+    "MAX_ENTRIES",
+    "MAX_FAILED_LOGIN_ENTRIES",
+    "PREFIX",
+    "create_audit_router",
+    "get_audit_plugin",
+]

qodalis_cli_server_plugin_audit-1.0.0b18/qodalis_cli_audit/cli_audit_builder.py

@@ -0,0 +1,124 @@
+"""Fluent builder for the audit plugin.
+
+Usage::
+
+    audit_plugin = CliAuditBuilder().build()       # in memory, the latest 1000 entries
+    # or keep the log elsewhere:
+    audit_plugin = CliAuditBuilder().set_store(MyAuditStore()).build()
+    result.mount_plugin(audit_plugin)
+
+The users plugin mounts one itself (with its own ``set_audit_store``, if any),
+so a host that only mounts the users plugin keeps its audit log.  A server
+serves one audit log: mounting a second audit plugin (or the same one again)
+adds no routes; an explicitly set store replaces the default one, and of two
+set stores the one mounted last is kept.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Awaitable, Callable, Optional
+
+from fastapi import APIRouter, Request
+
+from qodalis_cli_server_abstractions.audit import IAuditStore
+
+from .cli_audit_controller import create_audit_router
+from .in_memory_audit_store import InMemoryAuditStore
+
+PREFIX = "/api/v1/qcli/audit"
+
+#: Attribute of the server result holding the audit plugin that serves it.
+_SERVER_ATTR = "_qcli_audit_plugin"
+
+#: ``authorize(request, permission)`` returns the caller or raises an
+#: ``HTTPException`` (rendered as ``{"error": detail}``).
+Authorizer = Callable[[Request, str], Awaitable[Any]]
+StoreListener = Callable[[IAuditStore], None]
+
+
+def get_audit_plugin(server: Any) -> Optional[CliAuditPlugin]:
+    """The audit plugin mounted on ``server`` (a ``CliServerResult``), or ``None``."""
+    return getattr(server, _SERVER_ATTR, None)
+
+
+@dataclass
+class CliAuditPlugin:
+    """The built audit plugin: mount it with ``CliServerResult.mount_plugin``.
+
+    ``store`` is the log; record a host's own changes with
+    ``await plugin.store.log(AuditEntry(...))``.
+    """
+
+    prefix: str
+    store: IAuditStore
+    #: ``True`` when the store was set (not the default in-memory one).
+    store_set: bool = False
+    #: Checks the caller of the audit routes itself.  ``None`` (default)
+    #: leaves it to the server's route policy (``audit:read`` / ``audit:clear``
+    #: with the users plugin's server protection).  The users plugin sets it
+    #: when it does not protect the whole server.
+    authorize: Optional[Authorizer] = None
+    router: APIRouter = field(init=False, repr=False)
+    _listeners: list = field(default_factory=list, repr=False)
+
+    def __post_init__(self) -> None:
+        self.router = create_audit_router(self)
+
+    def use_store(self, store: IAuditStore, *, explicit: bool = True) -> None:
+        """Keep the log in ``store`` from now on (listeners are told)."""
+        self.store_set = self.store_set or explicit
+        if store is self.store:
+            return
+        self.store = store
+        for listener in list(self._listeners):
+            listener(store)
+
+    def on_store_changed(self, listener: StoreListener) -> None:
+        """Call ``listener(store)`` whenever the store is replaced (e.g. the
+        users plugin records its events in the store of the audit plugin it
+        joined)."""
+        self._listeners.append(listener)
+
+    def before_mount(self, server: Any) -> bool:
+        """Hook of ``CliServerResult.mount_plugin``: ``False`` when the server
+        already has an audit plugin (this one or another), which then serves
+        both; the routes are added once."""
+        serving = get_audit_plugin(server)
+        if serving is None:
+            setattr(server, _SERVER_ATTR, self)
+            return True
+        if serving is not self:
+            serving._join(self)
+        return False
+
+    def _join(self, other: CliAuditPlugin) -> None:
+        """``other`` was mounted on a server this plugin serves: one log."""
+        if other.store_set:
+            self.use_store(other.store)
+        if self.authorize is None and other.authorize is not None:
+            self.authorize = other.authorize
+        # ``other`` (and whoever follows it, e.g. the users plugin) records
+        # in this plugin's store, now and after it is replaced.
+        other.use_store(self.store, explicit=False)
+        self.on_store_changed(lambda store: other.use_store(store, explicit=False))
+
+
+class CliAuditBuilder:
+    """Fluent builder for the audit plugin."""
+
+    def __init__(self) -> None:
+        self._store: IAuditStore | None = None
+
+    def set_store(self, store: IAuditStore) -> CliAuditBuilder:
+        """Keep the log in ``store`` (default: in memory, the latest 1000
+        entries, failed sign-ins apart, at most 200)."""
+        self._store = store
+        return self
+
+    def build(self) -> CliAuditPlugin:
+        return CliAuditPlugin(
+            prefix=PREFIX,
+            store=self._store or InMemoryAuditStore(),
+            store_set=self._store is not None,
+        )

qodalis_cli_server_plugin_audit-1.0.0b18/qodalis_cli_audit/cli_audit_controller.py

@@ -0,0 +1,129 @@
+"""The audit log API — ``/api/v1/qcli/audit``.
+
+``GET`` lists entries (``audit:read`` on a protected server), ``DELETE``
+clears the log (``audit:clear``).  The admin dashboard's Audit page and the
+CLI's ``audit`` command read it.  Refusals answer ``{"error": "..."}``, like
+the users API.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from fastapi import APIRouter, HTTPException, Request, Response
+from fastapi.responses import JSONResponse
+
+from qodalis_cli_server_abstractions.audit import AuditEntry, AuditQueryOptions
+
+if TYPE_CHECKING:
+    from .cli_audit_builder import CliAuditPlugin
+
+#: Entries returned when the request names no limit.
+DEFAULT_AUDIT_LIMIT = 100
+#: The most entries one request returns, so a database store never loads the
+#: whole log.
+MAX_AUDIT_LIMIT = 1000
+#: The event recorded after the log was cleared.
+AUDIT_CLEARED_EVENT = "audit_cleared"
+
+AUDIT_READ = "audit:read"
+AUDIT_CLEAR = "audit:clear"
+
+#: Key under ``scope["state"]`` where an auth plugin stores the caller
+#: (shared with ``qodalis_cli.security``; kept local so the plugin does not
+#: depend on the server package).
+AUTH_STATE_KEY = "qcli_auth"
+
+BAD_PAGING = "limit and offset must be integers >= 0"
+
+
+def _error(status: int, message: Any) -> JSONResponse:
+    return JSONResponse({"error": str(message)}, status_code=status)
+
+
+def _scope_caller(request: Request) -> Any:
+    state = request.scope.get("state")
+    if isinstance(state, dict):
+        return state.get(AUTH_STATE_KEY)
+    return getattr(state, AUTH_STATE_KEY, None) if state is not None else None
+
+
+def _paging(request: Request, name: str) -> int | None:
+    """``None`` when absent or empty; raises ``ValueError`` when not an integer >= 0."""
+    raw = request.query_params.get(name)
+    if raw is None or raw == "":
+        return None
+    value = int(raw.strip())  # ValueError for "x", "1.5", ...
+    if value < 0:
+        raise ValueError(name)
+    return value
+
+
+def create_audit_router(plugin: CliAuditPlugin) -> APIRouter:
+    """The audit routes.  They read ``plugin.store`` on every request, so a
+    store set after the router was built is used."""
+    router = APIRouter(tags=["audit"])
+
+    async def caller_of(request: Request, permission: str) -> Any:
+        if plugin.authorize is not None:
+            return await plugin.authorize(request, permission)
+        caller = _scope_caller(request)
+        # Defensive: the route policy of an auth plugin already checked it.
+        can = getattr(caller, "can", None)
+        if callable(can) and not can(permission):
+            raise HTTPException(403, f"missing permission: {permission}")
+        return caller
+
+    async def list_entries(request: Request) -> Any:
+        """Entries newest first, filtered by ``event``, ``username`` (the user
+        an entry is about) and ``actor`` (who did it), all exact and
+        case-insensitive; paged with ``limit`` (default 100, at most 1000) and
+        ``offset``."""
+        try:
+            await caller_of(request, AUDIT_READ)
+        except HTTPException as exc:
+            return _error(exc.status_code, exc.detail)
+        try:
+            limit = _paging(request, "limit")
+            offset = _paging(request, "offset")
+        except ValueError:
+            return _error(400, BAD_PAGING)
+        query = request.query_params
+        entries = await plugin.store.get_entries(AuditQueryOptions(
+            event=query.get("event") or None,
+            username=query.get("username") or None,
+            actor=query.get("actor") or None,
+            limit=DEFAULT_AUDIT_LIMIT if limit is None else min(limit, MAX_AUDIT_LIMIT),
+            offset=offset or None,
+        ))
+        return [entry.to_dict() for entry in entries]
+
+    async def clear_entries(request: Request) -> Response:
+        """Clears the log, then records who cleared it (``audit_cleared``)."""
+        try:
+            caller = await caller_of(request, AUDIT_CLEAR)
+        except HTTPException as exc:
+            return _error(exc.status_code, exc.detail)
+        await plugin.store.clear()
+        user = getattr(caller, "user", None)
+        name = getattr(user, "name", None)
+        user_id = getattr(user, "id", None)
+        await plugin.store.log(AuditEntry(
+            event=AUDIT_CLEARED_EVENT,
+            username=name or "",
+            user_id=user_id,
+            details="audit log cleared",
+            actor=name,
+            actor_id=user_id,
+            metadata={"remoteAddress": request.client.host if request.client else None},
+        ))
+        return Response(status_code=204)
+
+    # Both "" and "/" so neither form redirects.
+    for path, in_schema in (("", True), ("/", False)):
+        router.add_api_route(path, list_entries, methods=["GET"], include_in_schema=in_schema)
+        router.add_api_route(
+            path, clear_entries, methods=["DELETE"], status_code=204,
+            response_class=Response, include_in_schema=in_schema,
+        )
+    return router

qodalis_cli_server_plugin_audit-1.0.0b18/qodalis_cli_audit/in_memory_audit_store.py

@@ -0,0 +1,69 @@
+"""In-memory implementation of :class:`IAuditStore`.
+
+Keeps the latest 1000 entries; failed sign-ins (``login_failed``) are capped
+separately (the latest 200) so a flood of them cannot evict the rest.
+"""
+
+from __future__ import annotations
+
+import itertools
+from collections import deque
+
+from qodalis_cli_server_abstractions.audit import AuditEntry, AuditQueryOptions, IAuditStore
+
+MAX_ENTRIES = 1000
+MAX_FAILED_LOGIN_ENTRIES = 200
+#: The event of a failed sign-in (users plugin), kept apart from the rest.
+FAILED_LOGIN_EVENT = "login_failed"
+
+
+class InMemoryAuditStore(IAuditStore):
+    def __init__(
+        self,
+        max_entries: int = MAX_ENTRIES,
+        max_failed_login_entries: int = MAX_FAILED_LOGIN_ENTRIES,
+    ) -> None:
+        self.max_entries = max_entries if max_entries > 0 else MAX_ENTRIES
+        self.max_failed_login_entries = (
+            max_failed_login_entries if max_failed_login_entries > 0 else MAX_FAILED_LOGIN_ENTRIES
+        )
+        self._seq = itertools.count()
+        self._entries: deque[tuple[int, AuditEntry]] = deque(maxlen=self.max_entries)
+        self._failed: deque[tuple[int, AuditEntry]] = deque(maxlen=self.max_failed_login_entries)
+
+    async def log(self, entry: AuditEntry) -> None:
+        target = self._failed if entry.event == FAILED_LOGIN_EVENT else self._entries
+        target.append((next(self._seq), entry))
+
+    async def get_entries(self, options: AuditQueryOptions | None = None) -> list[AuditEntry]:
+        # Newest recorded first.
+        merged = sorted([*self._entries, *self._failed], key=lambda item: item[0], reverse=True)
+        result = [entry for _, entry in merged]
+        if options:
+            if options.event:
+                event = options.event.lower()
+                result = [e for e in result if e.event.lower() == event]
+            if options.username:
+                username = options.username.lower()
+                result = [e for e in result if e.username.lower() == username]
+            if options.actor:
+                actor = options.actor.lower()
+                result = [e for e in result if (e.actor or "").lower() == actor]
+            if options.offset is not None and options.offset > 0:
+                result = result[options.offset:]
+            if options.limit is not None and options.limit >= 0:
+                result = result[: options.limit]
+        return result
+
+    async def prune(self, before: int) -> int:
+        removed = 0
+        for entries in (self._entries, self._failed):
+            kept = [item for item in entries if item[1].timestamp >= before]
+            removed += len(entries) - len(kept)
+            entries.clear()
+            entries.extend(kept)
+        return removed
+
+    async def clear(self) -> None:
+        self._entries.clear()
+        self._failed.clear()