msaas-audit-log 0.1.0__tar.gz

msaas_audit_log-0.1.0/.gitignore

@@ -0,0 +1,23 @@
+node_modules/
+dist/
+.next/
+.turbo/
+*.pyc
+__pycache__/
+.venv/
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+.env
+.env.*
+!.env.example
+!.env.*.example
+!.env.*.template
+.DS_Store
+coverage/
+
+# Runtime artifacts
+logs_llm/
+vectors.db
+vectors.db-shm
+vectors.db-wal

msaas_audit_log-0.1.0/PKG-INFO

@@ -0,0 +1,16 @@
+Metadata-Version: 2.4
+Name: msaas-audit-log
+Version: 0.1.0
+Summary: Immutable audit log library with PostgreSQL storage for the Willian SaaS platform
+License: MIT
+Requires-Python: >=3.12
+Requires-Dist: asyncpg>=0.30.0
+Requires-Dist: fastapi>=0.115.0
+Requires-Dist: msaas-api-core
+Requires-Dist: msaas-errors
+Requires-Dist: pydantic>=2.0
+Provides-Extra: dev
+Requires-Dist: httpx>=0.27.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.24.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.8.0; extra == 'dev'

msaas_audit_log-0.1.0/pyproject.toml

@@ -0,0 +1,40 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "msaas-audit-log"
+version = "0.1.0"
+description = "Immutable audit log library with PostgreSQL storage for the Willian SaaS platform"
+requires-python = ">=3.12"
+license = { text = "MIT" }
+dependencies = [
+    "msaas-api-core",
+    "msaas-errors",
+    "fastapi>=0.115.0",
+    "pydantic>=2.0",
+    "asyncpg>=0.30.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.24.0",
+    "httpx>=0.27.0",
+    "ruff>=0.8.0",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/audit_log"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+
+[tool.ruff]
+target-version = "py312"
+line-length = 100
+
+[tool.uv.sources]
+msaas-api-core = { workspace = true }
+msaas-errors = { workspace = true }

msaas_audit_log-0.1.0/src/audit_log/__init__.py

@@ -0,0 +1,39 @@
+"""Willian Audit -- Immutable audit log library with PostgreSQL storage."""
+
+from audit_log.config import AuditConfig, init_audit
+from audit_log.middleware import AuditMiddleware
+from audit_log.models import AuditEvent, AuditQuery
+from audit_log.router import AuditRouter
+from audit_log.actions import AuditActions
+from audit_log.decorators import (
+    audit_document,
+    audit_folder,
+    audit_log,
+    audit_organization,
+    audit_user,
+)
+from audit_log.service import (
+    get_audit_trail,
+    get_resource_history,
+    log_action,
+    log_change,
+)
+
+__all__ = [
+    "AuditActions",
+    "AuditConfig",
+    "AuditEvent",
+    "AuditMiddleware",
+    "AuditQuery",
+    "AuditRouter",
+    "audit_document",
+    "audit_folder",
+    "audit_log",
+    "audit_organization",
+    "audit_user",
+    "get_audit_trail",
+    "get_resource_history",
+    "init_audit",
+    "log_action",
+    "log_change",
+]

msaas_audit_log-0.1.0/src/audit_log/actions.py

@@ -0,0 +1,92 @@
+"""Predefined audit action types registry."""
+
+from __future__ import annotations
+
+
+class AuditActions:
+    """Registry of standard audit action types.
+
+    Usage:
+        from audit_log.actions import AuditActions
+        await log_action(action=AuditActions.USER_LOGIN, ...)
+    """
+
+    # Authentication
+    USER_LOGIN = "user.login"
+    USER_LOGOUT = "user.logout"
+    USER_LOGIN_FAILED = "user.login_failed"
+    USER_PASSWORD_RESET = "user.password_reset"
+    USER_PASSWORD_CHANGED = "user.password_changed"
+    USER_MFA_ENABLED = "user.mfa_enabled"
+    USER_MFA_DISABLED = "user.mfa_disabled"
+    API_KEY_CREATED = "api_key.created"
+    API_KEY_REVOKED = "api_key.revoked"
+
+    # User management
+    USER_CREATED = "user.created"
+    USER_UPDATED = "user.updated"
+    USER_DELETED = "user.deleted"
+    USER_INVITED = "user.invited"
+    USER_ROLE_CHANGED = "user.role_changed"
+    USER_DEACTIVATED = "user.deactivated"
+
+    # Documents
+    DOCUMENT_CREATED = "document.created"
+    DOCUMENT_UPDATED = "document.updated"
+    DOCUMENT_DELETED = "document.deleted"
+    DOCUMENT_VIEWED = "document.viewed"
+    DOCUMENT_DOWNLOADED = "document.downloaded"
+    DOCUMENT_SHARED = "document.shared"
+    DOCUMENT_UNSHARED = "document.unshared"
+    DOCUMENT_MOVED = "document.moved"
+    DOCUMENT_COPIED = "document.copied"
+    DOCUMENT_RESTORED = "document.restored"
+    DOCUMENT_VERSION_CREATED = "document.version_created"
+
+    # Folders
+    FOLDER_CREATED = "folder.created"
+    FOLDER_UPDATED = "folder.updated"
+    FOLDER_DELETED = "folder.deleted"
+    FOLDER_MOVED = "folder.moved"
+    FOLDER_SHARED = "folder.shared"
+    FOLDER_UNSHARED = "folder.unshared"
+
+    # Processing
+    PROCESSING_STARTED = "processing.started"
+    PROCESSING_COMPLETED = "processing.completed"
+    PROCESSING_FAILED = "processing.failed"
+
+    # Organization
+    ORG_CREATED = "organization.created"
+    ORG_UPDATED = "organization.updated"
+    ORG_DELETED = "organization.deleted"
+    ORG_MEMBER_ADDED = "organization.member_added"
+    ORG_MEMBER_REMOVED = "organization.member_removed"
+    ORG_SETTINGS_CHANGED = "organization.settings_changed"
+    ORG_PLAN_CHANGED = "organization.plan_changed"
+
+    # Billing
+    SUBSCRIPTION_CREATED = "subscription.created"
+    SUBSCRIPTION_UPDATED = "subscription.updated"
+    SUBSCRIPTION_CANCELLED = "subscription.cancelled"
+    PAYMENT_SUCCEEDED = "payment.succeeded"
+    PAYMENT_FAILED = "payment.failed"
+
+    # Sharing
+    SHARE_LINK_CREATED = "share_link.created"
+    SHARE_LINK_ACCESSED = "share_link.accessed"
+    SHARE_LINK_REVOKED = "share_link.revoked"
+
+    # System
+    SYSTEM_MAINTENANCE = "system.maintenance"
+    SYSTEM_CONFIG_CHANGED = "system.config_changed"
+    SYSTEM_EXPORT_REQUESTED = "system.export_requested"
+
+    @classmethod
+    def all_actions(cls) -> list[str]:
+        """Return all registered action types."""
+        return [
+            v
+            for k, v in vars(cls).items()
+            if isinstance(v, str) and not k.startswith("_") and k != "all_actions"
+        ]

msaas_audit_log-0.1.0/src/audit_log/config.py

@@ -0,0 +1,80 @@
+"""Audit module configuration and initialization."""
+
+from __future__ import annotations
+
+import asyncpg
+from pydantic import BaseModel
+
+
+_config: AuditConfig | None = None
+_pool: asyncpg.Pool | None = None
+
+
+class AuditConfig(BaseModel):
+    """Configuration for the audit log module.
+
+    Args:
+        database_url: PostgreSQL connection string.
+        table_name: Name of the audit events table.
+        retention_days: Number of days to retain events before purge eligibility.
+        pool_min_size: Minimum connections in the asyncpg pool.
+        pool_max_size: Maximum connections in the asyncpg pool.
+    """
+
+    database_url: str
+    table_name: str = "audit_events"
+    retention_days: int = 90
+    pool_min_size: int = 2
+    pool_max_size: int = 10
+
+
+async def init_audit(config: AuditConfig) -> asyncpg.Pool:
+    """Initialize the audit module: store config and create the connection pool.
+
+    Must be called before any store or service operations.
+
+    Returns:
+        The created asyncpg connection pool.
+    """
+    global _config, _pool
+    _config = config
+    _pool = await asyncpg.create_pool(
+        dsn=config.database_url,
+        min_size=config.pool_min_size,
+        max_size=config.pool_max_size,
+    )
+    return _pool
+
+
+def get_config() -> AuditConfig:
+    """Return the current module configuration.
+
+    Raises:
+        RuntimeError: If init_audit() has not been called.
+    """
+    if _config is None:
+        raise RuntimeError("Audit module not initialized. Call init_audit() first.")
+    return _config
+
+
+def get_pool() -> asyncpg.Pool:
+    """Return the current connection pool.
+
+    Raises:
+        RuntimeError: If init_audit() has not been called.
+    """
+    if _pool is None:
+        raise RuntimeError("Audit module not initialized. Call init_audit() first.")
+    return _pool
+
+
+def set_config(config: AuditConfig) -> None:
+    """Override the configuration (useful for testing)."""
+    global _config
+    _config = config
+
+
+def set_pool(pool: asyncpg.Pool) -> None:
+    """Override the connection pool (useful for testing)."""
+    global _pool
+    _pool = pool

msaas_audit_log-0.1.0/src/audit_log/decorators.py

@@ -0,0 +1,109 @@
+"""Decorator-based audit logging for FastAPI route handlers."""
+
+from __future__ import annotations
+
+import functools
+import logging
+from collections.abc import Callable
+from typing import Any
+
+from audit_log.service import log_action
+
+logger = logging.getLogger(__name__)
+
+
+def audit_log(
+    action: str,
+    resource_type: str,
+    resource_id_param: str = "id",
+    actor_id_param: str | None = None,
+) -> Callable:
+    """Decorator that automatically logs an audit event after a route handler succeeds.
+
+    Usage:
+        @router.post("/documents/{id}/approve")
+        @audit_log(action="document.approved", resource_type="document")
+        async def approve_document(id: str, current_user: User = Depends(get_user)):
+            ...
+
+    Args:
+        action: The action identifier (e.g., "document.created").
+        resource_type: The type of resource being acted upon.
+        resource_id_param: Name of the function parameter containing the resource ID.
+        actor_id_param: Name of the parameter containing actor ID. If None,
+            looks for 'current_user' with an 'id' attribute.
+    """
+
+    def decorator(func: Callable) -> Callable:
+        @functools.wraps(func)
+        async def wrapper(*args: Any, **kwargs: Any) -> Any:
+            result = await func(*args, **kwargs)
+
+            try:
+                resource_id = str(kwargs.get(resource_id_param, "unknown"))
+                actor_id = _extract_actor_id(kwargs, actor_id_param)
+                ip_address = _extract_ip(kwargs)
+                user_agent = _extract_user_agent(kwargs)
+
+                await log_action(
+                    actor_id=actor_id,
+                    action=action,
+                    resource_type=resource_type,
+                    resource_id=resource_id,
+                    ip_address=ip_address,
+                    user_agent=user_agent,
+                    metadata={"decorated": True},
+                )
+            except Exception:
+                logger.warning("Failed to log audit event for %s", action, exc_info=True)
+
+            return result
+
+        return wrapper
+
+    return decorator
+
+
+def audit_document(action: str, resource_id_param: str = "id") -> Callable:
+    """Shorthand for @audit_log with resource_type='document'."""
+    return audit_log(action=action, resource_type="document", resource_id_param=resource_id_param)
+
+
+def audit_folder(action: str, resource_id_param: str = "id") -> Callable:
+    """Shorthand for @audit_log with resource_type='folder'."""
+    return audit_log(action=action, resource_type="folder", resource_id_param=resource_id_param)
+
+
+def audit_user(action: str, resource_id_param: str = "id") -> Callable:
+    """Shorthand for @audit_log with resource_type='user'."""
+    return audit_log(action=action, resource_type="user", resource_id_param=resource_id_param)
+
+
+def audit_organization(action: str, resource_id_param: str = "id") -> Callable:
+    """Shorthand for @audit_log with resource_type='organization'."""
+    return audit_log(
+        action=action, resource_type="organization", resource_id_param=resource_id_param
+    )
+
+
+def _extract_actor_id(kwargs: dict[str, Any], actor_id_param: str | None) -> str:
+    if actor_id_param and actor_id_param in kwargs:
+        return str(kwargs[actor_id_param])
+    current_user = kwargs.get("current_user")
+    if current_user and hasattr(current_user, "id"):
+        return str(current_user.id)
+    return "system"
+
+
+def _extract_ip(kwargs: dict[str, Any]) -> str | None:
+    request = kwargs.get("request")
+    if request and hasattr(request, "client") and request.client:
+        return request.client.host
+    return None
+
+
+def _extract_user_agent(kwargs: dict[str, Any]) -> str | None:
+    request = kwargs.get("request")
+    if request and hasattr(request, "headers"):
+        return request.headers.get("user-agent")
+    return None

msaas_audit_log-0.1.0/src/audit_log/middleware.py

@@ -0,0 +1,68 @@
+"""FastAPI middleware that captures request metadata for audit events."""
+
+from __future__ import annotations
+
+from contextvars import ContextVar
+from typing import TYPE_CHECKING
+
+from starlette.middleware.base import BaseHTTPMiddleware, RequestResponseEndpoint
+from starlette.requests import Request
+from starlette.responses import Response
+
+if TYPE_CHECKING:
+    from starlette.types import ASGIApp
+
+
+_audit_ip: ContextVar[str | None] = ContextVar("audit_ip", default=None)
+_audit_user_agent: ContextVar[str | None] = ContextVar("audit_user_agent", default=None)
+
+
+def get_request_ip() -> str | None:
+    """Return the client IP address captured by the audit middleware."""
+    return _audit_ip.get()
+
+
+def get_request_user_agent() -> str | None:
+    """Return the client User-Agent captured by the audit middleware."""
+    return _audit_user_agent.get()
+
+
+class AuditMiddleware(BaseHTTPMiddleware):
+    """Middleware that extracts IP address and User-Agent into context variables.
+
+    When this middleware is active, audit service functions can automatically
+    pick up request metadata without the caller having to pass them explicitly.
+
+    The middleware reads ``X-Forwarded-For`` when present (common behind
+    reverse proxies), falling back to the direct client IP.
+
+    Usage::
+
+        from fastapi import FastAPI
+        from audit_log import AuditMiddleware
+
+        app = FastAPI()
+        app.add_middleware(AuditMiddleware)
+    """
+
+    def __init__(self, app: ASGIApp) -> None:
+        super().__init__(app)
+
+    async def dispatch(self, request: Request, call_next: RequestResponseEndpoint) -> Response:
+        # Extract client IP, preferring X-Forwarded-For for proxied setups.
+        forwarded = request.headers.get("x-forwarded-for")
+        if forwarded:
+            ip = forwarded.split(",")[0].strip()
+        else:
+            ip = request.client.host if request.client else None
+
+        user_agent = request.headers.get("user-agent")
+
+        ip_token = _audit_ip.set(ip)
+        ua_token = _audit_user_agent.set(user_agent)
+
+        try:
+            return await call_next(request)
+        finally:
+            _audit_ip.reset(ip_token)
+            _audit_user_agent.reset(ua_token)

msaas_audit_log-0.1.0/src/audit_log/models.py

@@ -0,0 +1,52 @@
+"""Pydantic models for audit events and queries."""
+
+from __future__ import annotations
+
+import enum
+from datetime import datetime
+from uuid import UUID
+
+from pydantic import BaseModel, Field
+
+
+class ActorType(str, enum.Enum):
+    """Type of actor that triggered the audit event."""
+
+    USER = "user"
+    SYSTEM = "system"
+    API_KEY = "api_key"
+
+
+class AuditEvent(BaseModel):
+    """An immutable audit event record.
+
+    Captures who did what, to which resource, and when.
+    """
+
+    id: UUID
+    timestamp: datetime
+    actor_id: str
+    actor_type: ActorType = ActorType.USER
+    action: str
+    resource_type: str
+    resource_id: str
+    changes: dict = Field(default_factory=dict)
+    metadata: dict = Field(default_factory=dict)
+    ip_address: str | None = None
+    user_agent: str | None = None
+
+
+class AuditQuery(BaseModel):
+    """Filters for querying audit events.
+
+    All filter fields are optional. Only non-None fields are applied.
+    """
+
+    actor_id: str | None = None
+    action: str | None = None
+    resource_type: str | None = None
+    resource_id: str | None = None
+    start_date: datetime | None = None
+    end_date: datetime | None = None
+    limit: int = Field(default=50, ge=1, le=1000)
+    offset: int = Field(default=0, ge=0)

msaas_audit_log-0.1.0/src/audit_log/router.py

@@ -0,0 +1,146 @@
+"""FastAPI router factory for audit log endpoints."""
+
+from __future__ import annotations
+
+from typing import Any
+from uuid import UUID
+
+from fastapi import APIRouter, Depends, Query
+from pydantic import BaseModel
+
+from audit_log.config import get_config
+from audit_log.models import AuditEvent
+from audit_log.service import get_audit_trail, get_resource_history
+from audit_log.store import get_event, purge_old_events
+from errors import NotFoundError
+
+
+class AuditListResponse(BaseModel):
+    """Response model for paginated audit event list."""
+
+    items: list[AuditEvent]
+    total: int
+    page: int
+    per_page: int
+
+
+class PurgeResponse(BaseModel):
+    """Response model for purge operations."""
+
+    deleted: int
+    retention_days: int
+
+
+def AuditRouter(
+    *,
+    get_user_id: Any | None = None,
+    is_admin: Any | None = None,
+    prefix: str = "/audit",
+    tags: list[str] | None = None,
+) -> APIRouter:
+    """Create a FastAPI router for audit log endpoints.
+
+    Args:
+        get_user_id: Optional FastAPI dependency returning the current user's ID.
+            Used for actor-scoped queries. If None, actor endpoints are still
+            available but require explicit actor_id.
+        is_admin: Optional FastAPI dependency that gates admin-only endpoints
+            (e.g., purge). Should raise HTTPException(403) if not authorized.
+            If None, purge endpoint is available without restriction.
+        prefix: URL prefix for all routes. Defaults to ``/audit``.
+        tags: OpenAPI tags for the router.
+
+    Returns:
+        A configured APIRouter.
+
+    Example::
+
+        from audit_log import AuditRouter
+
+        async def require_admin(request: Request) -> None:
+            if not request.state.user.is_admin:
+                raise AuthorizationError("Admin required")
+
+        router = AuditRouter(is_admin=require_admin)
+        app.include_router(router)
+    """
+    router = APIRouter(prefix=prefix, tags=tags or ["audit"])
+
+    @router.get("", response_model=AuditListResponse)
+    async def list_audit_events(
+        actor_id: str | None = Query(None, description="Filter by actor ID"),
+        action: str | None = Query(None, description="Filter by action"),
+        resource_type: str | None = Query(None, description="Filter by resource type"),
+        resource_id: str | None = Query(None, description="Filter by resource ID"),
+        page: int = Query(1, ge=1, description="Page number"),
+        per_page: int = Query(50, ge=1, le=1000, description="Items per page"),
+    ) -> AuditListResponse:
+        """List audit events with optional filters and pagination."""
+        result = await get_audit_trail(
+            actor_id=actor_id,
+            action=action,
+            resource_type=resource_type,
+            resource_id=resource_id,
+            page=page,
+            per_page=per_page,
+        )
+        return AuditListResponse(**result)
+
+    @router.get("/{event_id}", response_model=AuditEvent)
+    async def get_audit_event(event_id: UUID) -> AuditEvent:
+        """Get a single audit event by ID."""
+        event = await get_event(event_id)
+        if event is None:
+            raise NotFoundError("Audit event not found")
+        return event
+
+    @router.get("/resource/{resource_type}/{resource_id}", response_model=AuditListResponse)
+    async def get_resource_audit_history(
+        resource_type: str,
+        resource_id: str,
+        page: int = Query(1, ge=1, description="Page number"),
+        per_page: int = Query(50, ge=1, le=1000, description="Items per page"),
+    ) -> AuditListResponse:
+        """Get the audit trail for a specific resource."""
+        result = await get_resource_history(
+            resource_type,
+            resource_id,
+            page=page,
+            per_page=per_page,
+        )
+        return AuditListResponse(**result)
+
+    @router.get("/actor/{actor_id}", response_model=AuditListResponse)
+    async def get_actor_audit_trail(
+        actor_id: str,
+        page: int = Query(1, ge=1, description="Page number"),
+        per_page: int = Query(50, ge=1, le=1000, description="Items per page"),
+    ) -> AuditListResponse:
+        """Get the audit trail for a specific actor."""
+        result = await get_audit_trail(
+            actor_id=actor_id,
+            page=page,
+            per_page=per_page,
+        )
+        return AuditListResponse(**result)
+
+    # Build the purge endpoint dependencies list.
+    purge_deps: list[Any] = []
+    if is_admin is not None:
+        purge_deps.append(Depends(is_admin))
+
+    @router.post("/purge", response_model=PurgeResponse, dependencies=purge_deps)
+    async def purge_events(
+        retention_days: int | None = Query(
+            None,
+            ge=1,
+            description="Override retention period (days). Defaults to config value.",
+        ),
+    ) -> PurgeResponse:
+        """Purge audit events older than the retention period. Admin only."""
+        config = get_config()
+        days = retention_days if retention_days is not None else config.retention_days
+        deleted = await purge_old_events(days)
+        return PurgeResponse(deleted=deleted, retention_days=days)
+
+    return router