fastapi-admin-kit 0.1.0__py3-none-any.whl

fastapi_admin_kit/audit/event_bus.py

@@ -0,0 +1,96 @@
+"""Audit event bus — publish/subscribe system for audit events."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any
+
+from fastapi_admin_kit.audit.diff import snapshot
+from fastapi_admin_kit.audit.events import AuditEvent
+
+
+class AuditEventBus:
+    """Central event bus for audit events.
+
+    The listener publishes events here. Loggers and other subscribers
+    consume them. This decouples the SQLAlchemy event hooks from the
+    audit logging implementation.
+    """
+
+    def __init__(self) -> None:
+        self._listeners: dict[str, list[Callable[[AuditEvent], None]]] = {
+            "CREATE": [],
+            "UPDATE": [],
+            "DELETE": [],
+        }
+
+    def subscribe(
+        self, event_type: str, listener: Callable[[AuditEvent], None]
+    ) -> None:
+        """Register a listener for a specific event type.
+
+        Args:
+            event_type: "CREATE", "UPDATE", or "DELETE"
+            listener: Callable that receives an AuditEvent
+        """
+        if event_type not in self._listeners:
+            self._listeners[event_type] = []
+        self._listeners[event_type].append(listener)
+
+    def publish(self, event: AuditEvent) -> None:
+        """Publish an event to all listeners of its type.
+
+        Args:
+            event: The AuditEvent to publish
+        """
+        for listener in self._listeners.get(event.event_type, []):
+            listener(event)
+
+    def emit_for_object(
+        self,
+        obj: Any,
+        event_type: str,
+        context: dict[str, Any],
+        changes: dict[str, Any] | None = None,
+        snapshot_data: dict[str, Any] | None = None,
+    ) -> None:
+        """Build an AuditEvent from a SQLAlchemy object and publish it.
+
+        All data is extracted from *snapshot_data* to avoid touching the
+        ORM object — critical inside ``after_flush`` where attributes are
+        expired on async sessions.
+
+        Args:
+            obj: The SQLAlchemy model instance (used only for class/table
+                metadata which are class-level, not instance attributes)
+            event_type: "CREATE", "UPDATE", or "DELETE"
+            context: Audit context dict
+            changes: Pre-computed diff (used for UPDATE)
+            snapshot_data: Pre-computed snapshot dict
+        """
+        obj_snapshot = snapshot_data if snapshot_data is not None else snapshot(obj)
+
+        # Extract id and repr from the snapshot to avoid accessing
+        # potentially-expired instance attributes.
+        object_id = str(obj_snapshot.get("id", ""))
+        object_repr = str(obj_snapshot.get("id", obj.__class__.__name__))[:255]
+
+        if event_type == "UPDATE" and changes is not None:
+            event_changes = changes
+        else:
+            event_changes = None
+
+        event = AuditEvent(
+            event_type=event_type,
+            model_name=obj.__class__.__name__,
+            table_name=obj.__tablename__,
+            object_id=object_id,
+            object_repr=object_repr,
+            changes=event_changes,
+            full_snapshot=obj_snapshot,
+            user_id=context.get("user_id"),
+            user_email=context.get("user_email"),
+            ip_address=context.get("ip_address"),
+            user_agent=context.get("user_agent"),
+        )
+        self.publish(event)

fastapi_admin_kit/audit/events.py

@@ -0,0 +1,48 @@
+"""Audit events — data structures for audit events."""
+
+from __future__ import annotations
+
+import datetime
+from dataclasses import asdict, dataclass
+from typing import Any
+
+
+@dataclass
+class AuditEvent:
+    """Represents a single audit event (CREATE, UPDATE, or DELETE).
+
+    This is a pure data structure with no side effects, making it
+    easy to test and serialize.
+    """
+
+    event_type: str  # "CREATE" | "UPDATE" | "DELETE"
+    model_name: str
+    table_name: str
+    object_id: str
+    object_repr: str = ""
+    changes: dict[str, Any] | None = None
+    full_snapshot: dict[str, Any] | None = None
+    user_id: int | None = None
+    user_email: str | None = None
+    ip_address: str | None = None
+    user_agent: str | None = None
+    timestamp: datetime.datetime | None = None
+
+    def __post_init__(self) -> None:
+        if self.timestamp is None:
+            self.timestamp = datetime.datetime.now(datetime.UTC)
+
+    def to_dict(self) -> dict[str, Any]:
+        """Serialize the event to a dictionary."""
+        data = asdict(self)
+        if self.timestamp is not None:
+            data["timestamp"] = self.timestamp.isoformat()
+        return data
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> AuditEvent:
+        """Deserialize an event from a dictionary."""
+        ts = data.get("timestamp")
+        if isinstance(ts, str):
+            data["timestamp"] = datetime.datetime.fromisoformat(ts)
+        return cls(**data)

fastapi_admin_kit/audit/listener.py

@@ -0,0 +1,159 @@
+"""Audit listener — SQLAlchemy event listeners that write audit rows atomically.
+
+AuditLog rows are created inside ``before_flush`` and added to the session
+via ``session.add()``.  SQLAlchemy re-runs ``before_flush`` until no new
+pending objects appear, so the audit rows ride along in the same flush pass.
+No IO, no queries, no ``MissingGreenlet`` — just already-loaded attributes.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from sqlalchemy import event
+from sqlalchemy.orm import Session
+from sqlalchemy.orm.attributes import instance_state
+
+from fastapi_admin_kit.audit.context import get_audit_context
+from fastapi_admin_kit.audit.diff import serialize_value
+from fastapi_admin_kit.audit.models import AuditLog
+
+
+def is_registered_model(obj: Any, registry: Any) -> bool:
+    """Check if a model class is registered with the admin."""
+    if not hasattr(obj, "__tablename__"):
+        return False
+    table_name = getattr(obj, "__tablename__")
+    return registry.get(table_name) is not None
+
+
+def _snapshot_from_committed(obj: Any) -> dict[str, Any]:
+    """Snapshot column values from the committed (pre-flush) state.
+
+    Uses SQLAlchemy attribute history to read the *old* values that were
+    in the database before the current pending changes.  No attribute
+    access that could trigger lazy-load I/O.
+    """
+    if not hasattr(obj, "__table__"):
+        return {}
+    mapper = instance_state(obj).manager.mapper
+    data: dict[str, Any] = {}
+    for column in mapper.columns:
+        attr = instance_state(obj).attrs[column.key]
+        history = attr.history
+        if history.deleted:
+            data[column.key] = serialize_value(history.deleted[0])
+        elif history.unchanged:
+            data[column.key] = serialize_value(history.unchanged[0])
+        else:
+            data[column.key] = serialize_value(getattr(obj, column.key))
+    return data
+
+
+def _snapshot_current(obj: Any) -> dict[str, Any]:
+    """Snapshot all mapped columns of a SQLAlchemy model instance."""
+    if not hasattr(obj, "__table__"):
+        return {}
+    from sqlalchemy.inspection import inspect as sa_inspect
+
+    mapper = sa_inspect(obj.__class__)
+    data: dict[str, Any] = {}
+    for column in mapper.columns:
+        data[column.key] = serialize_value(getattr(obj, column.key))
+    return data
+
+
+def _compute_diff(before: dict[str, Any], after: dict[str, Any]) -> dict[str, Any]:
+    """Compute changed fields between two snapshots.
+
+    Returns ``{"field": {"old": ..., "new": ...}}`` for each difference.
+    """
+    diff: dict[str, Any] = {}
+    all_keys = set(before.keys()) | set(after.keys())
+    for key in all_keys:
+        old_val = before.get(key)
+        new_val = after.get(key)
+        if old_val != new_val:
+            diff[key] = {"old": old_val, "new": new_val}
+    return diff
+
+
+def _build_audit_row(
+    obj: Any,
+    action: str,
+    context: dict[str, Any],
+    *,
+    changes: dict[str, Any] | None = None,
+    snapshot_data: dict[str, Any] | None = None,
+) -> AuditLog:
+    """Create an AuditLog row from an ORM object and audit context."""
+    snap = snapshot_data if snapshot_data is not None else _snapshot_current(obj)
+    return AuditLog(
+        action=action,
+        model_name=type(obj).__name__,
+        table_name=obj.__tablename__,
+        object_id=str(snap.get("id", getattr(obj, "id", ""))),
+        object_repr=str(obj)[:500],
+        changes=changes,
+        full_snapshot=snap,
+        user_id=context.get("user_id"),
+        user_email=context.get("user_email"),
+        ip_address=context.get("ip_address"),
+        user_agent=context.get("user_agent"),
+    )
+
+
+def attach_audit_listener(
+    session_factory: Any,
+    registry: Any,
+) -> None:
+    """Set up SQLAlchemy ``before_flush`` listener for audit logging.
+
+    Args:
+        session_factory: The session factory (sync or async).
+        registry: The AdminRegistry instance.
+    """
+
+    @event.listens_for(Session, "before_flush")
+    def before_flush(session: Session, flush_context: Any, instances: Any) -> None:
+        """Create AuditLog rows for all tracked mutations.
+
+        Runs inside the same flush pass — ``session.add()`` puts the
+        AuditLog into the pending set and SQLAlchemy will re-run
+        ``before_flush`` until no new objects appear.  No queries, no
+        lazy-loads, only already-loaded attribute history.
+        """
+        context = get_audit_context()
+
+        # ── INSERT ──────────────────────────────────────────────────
+        for obj in list(session.new):
+            if not is_registered_model(obj, registry):
+                continue
+            if obj.__tablename__ == AuditLog.__tablename__:
+                continue
+            row = _build_audit_row(obj, "CREATE", context)
+            session.add(row)
+
+        # ── UPDATE ──────────────────────────────────────────────────
+        for obj in list(session.dirty):
+            if not is_registered_model(obj, registry):
+                continue
+            if obj.__tablename__ == AuditLog.__tablename__:
+                continue
+            before = _snapshot_from_committed(obj)
+            after = _snapshot_current(obj)
+            diff = _compute_diff(before, after)
+            if not diff:
+                continue
+            row = _build_audit_row(obj, "UPDATE", context, changes=diff, snapshot_data=after)
+            session.add(row)
+
+        # ── DELETE ──────────────────────────────────────────────────
+        for obj in list(session.deleted):
+            if not is_registered_model(obj, registry):
+                continue
+            if obj.__tablename__ == AuditLog.__tablename__:
+                continue
+            snap = _snapshot_current(obj)
+            row = _build_audit_row(obj, "DELETE", context, snapshot_data=snap)
+            session.add(row)

fastapi_admin_kit/audit/logger.py

@@ -0,0 +1,28 @@
+"""Audit logger — interface for audit log persistence."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+
+from fastapi_admin_kit.audit.events import AuditEvent
+
+
+class AuditLogger(ABC):
+    """Abstract interface for persisting audit events.
+
+    Implementations handle the actual storage (database, file, etc.).
+    This separation allows testing audit logic without a database, and
+    swapping storage backends without changing the event flow.
+    """
+
+    @abstractmethod
+    def log_create(self, event: AuditEvent) -> None:
+        """Persist a CREATE audit event."""
+
+    @abstractmethod
+    def log_update(self, event: AuditEvent) -> None:
+        """Persist an UPDATE audit event."""
+
+    @abstractmethod
+    def log_delete(self, event: AuditEvent) -> None:
+        """Persist a DELETE audit event."""

fastapi_admin_kit/audit/middleware.py

@@ -0,0 +1,39 @@
+"""Audit middleware — sets and clears audit context from the request."""
+
+from __future__ import annotations
+
+from starlette.middleware.base import BaseHTTPMiddleware
+from starlette.requests import Request
+from starlette.responses import Response
+
+from fastapi_admin_kit.audit.context import clear_audit_context, set_audit_context
+
+
+class AuditContextMiddleware(BaseHTTPMiddleware):
+    """Middleware to set audit context from the request and clear it after.
+
+    Sets IP address and user-agent before the handler runs.  The user
+    identity (user_id, user_email) is added later by
+    :func:`fastapi_admin_kit.auth.identity.resolve_user` once the auth
+    dependency resolves the current user — which always happens before
+    any ``session.commit()`` that would trigger audit listeners.
+    """
+
+    async def dispatch(self, request: Request, call_next) -> Response:
+        context_data: dict = {}
+
+        if request.client is not None:
+            context_data["ip_address"] = request.client.host
+
+        user_agent = request.headers.get("user-agent")
+        if user_agent:
+            context_data["user_agent"] = user_agent
+
+        if context_data:
+            set_audit_context(context_data)
+
+        response = await call_next(request)
+
+        clear_audit_context()
+
+        return response

fastapi_admin_kit/audit/models.py

@@ -0,0 +1,53 @@
+"""SQLAlchemy model for the admin audit log."""
+
+from __future__ import annotations
+
+from sqlalchemy import (
+    JSON,
+    Column,
+    DateTime,
+    ForeignKey,
+    Index,
+    Integer,
+    String,
+    Text,
+)
+from sqlalchemy.sql import func
+
+from fastapi_admin_kit.models.base import Base
+
+
+class AuditLog(Base):
+    __tablename__ = "admin_audit_log"
+    __table_args__ = (
+        Index("idx_audit_model", "model_name", "table_name"),
+        Index("idx_audit_user", "user_id"),
+        Index("idx_audit_timestamp", "timestamp"),
+        Index("idx_audit_object", "table_name", "object_id"),
+    )
+
+    id = Column(Integer, primary_key=True, autoincrement=True)
+    user_id = Column(
+        Integer,
+        ForeignKey("admin_users.id", ondelete="SET NULL"),
+        nullable=True,
+    )
+    user_email = Column(String(255))
+    action = Column(String(10), nullable=False)  # CREATE | UPDATE | DELETE
+    model_name = Column(String(255), nullable=False)
+    table_name = Column(String(255), nullable=False)
+    object_id = Column(String(255), nullable=False)
+    object_repr = Column(String(500))
+    changes = Column(JSON)  # diff (null for CREATE/DELETE)
+    full_snapshot = Column(JSON)  # full object state at time of action
+    ip_address = Column(String(45))
+    user_agent = Column(Text)
+    timestamp = Column(DateTime(timezone=True), server_default=func.now())
+
+    def __str__(self) -> str:
+        return f"{self.action} {self.model_name}#{self.object_id}"
+
+    def __repr__(self) -> str:
+        return (
+            f"<AuditLog {self.action} {self.model_name}#{self.object_id}>"
+        )

fastapi_admin_kit/audit/sqlalchemy_logger.py

@@ -0,0 +1,58 @@
+"""SQLAlchemy audit logger — persists audit events to the database."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from fastapi_admin_kit.audit.events import AuditEvent
+from fastapi_admin_kit.audit.logger import AuditLogger
+from fastapi_admin_kit.audit.models import AuditLog
+
+
+class SqlAlchemyAuditLogger(AuditLogger):
+    """Writes AuditEvents to the admin_audit_log table.
+
+    Buffers AuditLog entries during synchronous SQLAlchemy event callbacks
+    (e.g. ``after_flush``) and flushes them to the database asynchronously
+    after the main transaction commits.  This avoids triggering implicit
+    autoflush inside a sync event handler, which would raise
+    ``MissingGreenlet`` with async sessions.
+    """
+
+    def __init__(self, session: Any = None) -> None:
+        self._session = session
+        self._pending: list[AuditLog] = []
+
+    def log_create(self, event: AuditEvent) -> None:
+        self._buffer(event)
+
+    def log_update(self, event: AuditEvent) -> None:
+        self._buffer(event)
+
+    def log_delete(self, event: AuditEvent) -> None:
+        self._buffer(event)
+
+    def _buffer(self, event: AuditEvent) -> None:
+        entry = AuditLog(
+            user_id=event.user_id,
+            user_email=event.user_email,
+            action=event.event_type,
+            model_name=event.model_name,
+            table_name=event.table_name,
+            object_id=event.object_id,
+            object_repr=event.object_repr,
+            changes=event.changes,
+            full_snapshot=event.full_snapshot,
+            ip_address=event.ip_address,
+            user_agent=event.user_agent,
+        )
+        self._pending.append(entry)
+
+    async def flush_pending(self, session: Any) -> None:
+        """Write all buffered entries to *session* and clear the buffer."""
+        if not self._pending:
+            return
+        for entry in self._pending:
+            session.add(entry)
+        self._pending.clear()
+        await session.flush()

fastapi_admin_kit/auth/__init__.py

@@ -0,0 +1,34 @@
+"""Auth module — models, session, AuthBackend, PermissionChecker, dependencies."""
+
+from __future__ import annotations
+
+from fastapi_admin_kit.auth.backend import AuthBackend, BuiltinAuthBackend
+from fastapi_admin_kit.auth.csrf import (
+    auth_redirect_handler,
+    require_csrf_token,
+    set_csrf_cookie,
+)
+from fastapi_admin_kit.auth.models import (
+    AdminPermission,
+    AdminRole,
+    AdminUser,
+    AdminUserPermission,
+)
+from fastapi_admin_kit.auth.session import (
+    SessionBackend,
+    SignedCookieSessionBackend,
+)
+
+__all__ = [
+    "AdminPermission",
+    "AdminRole",
+    "AdminUser",
+    "AdminUserPermission",
+    "AuthBackend",
+    "BuiltinAuthBackend",
+    "SessionBackend",
+    "SignedCookieSessionBackend",
+    "auth_redirect_handler",
+    "require_csrf_token",
+    "set_csrf_cookie",
+]

fastapi_admin_kit/auth/backend.py

@@ -0,0 +1,95 @@
+"""Auth backend — ABC + built-in implementation."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import TYPE_CHECKING, Any
+
+import bcrypt
+
+if TYPE_CHECKING:
+    from fastapi_admin_kit.auth.protocol import AdminUserProtocol
+
+
+class _PasswordHasher:
+    """Thin wrapper around bcrypt for hash/verify."""
+
+    @staticmethod
+    def hash(password: str) -> str:
+        return bcrypt.hashpw(password.encode(), bcrypt.gensalt()).decode()
+
+    @staticmethod
+    def verify(password: str, hashed: str) -> bool:
+        try:
+            return bcrypt.checkpw(password.encode(), hashed.encode())
+        except (ValueError, TypeError):
+            return False
+
+
+pwd_context = _PasswordHasher()
+
+
+class AuthBackend(ABC):
+    """Abstract authentication backend — verify credentials & load users."""
+
+    @abstractmethod
+    async def authenticate(
+        self, email: str, password: str, session: Any
+    ) -> AdminUserProtocol | None:
+        """Verify credentials. Return user object if valid, ``None`` otherwise."""
+        ...
+
+    @abstractmethod
+    async def get_user(
+        self, user_id: int | str, session: Any
+    ) -> AdminUserProtocol | None:
+        """Load user by PK. Return ``None`` if not found or inactive."""
+        ...
+
+    async def on_logout(self, user_id: int | str | None = None) -> None:
+        """Called after a user logs out. Override to perform cleanup."""
+        # Default implementation does nothing
+        return None
+
+
+class BuiltinAuthBackend(AuthBackend):
+    """Default backend that works with the built-in ``AdminUser`` model."""
+
+    async def authenticate(
+        self, email: str, password: str, session: Any
+    ) -> AdminUserProtocol | None:
+        from sqlalchemy import select
+
+        from fastapi_admin_kit.auth.models import AdminUser
+
+        result = await session.execute(
+            select(AdminUser).where(
+                AdminUser.email == email, AdminUser.is_active.is_(True)
+            )
+        )
+        user = result.scalar_one_or_none()
+
+        if not user:
+            return None
+        if not pwd_context.verify(password, user.hashed_password):
+            return None
+        return user
+
+    async def get_user(
+        self, user_id: int | str, session: Any
+    ) -> AdminUserProtocol | None:
+        from sqlalchemy import select
+        from sqlalchemy.orm import selectinload
+
+        from fastapi_admin_kit.auth.models import AdminUser
+
+        result = await session.execute(
+            select(AdminUser)
+            .options(selectinload(AdminUser.roles))
+            .where(AdminUser.id == user_id, AdminUser.is_active.is_(True))
+        )
+        return result.scalar_one_or_none()
+
+    async def on_logout(self, user_id: int | str | None = None) -> None:
+        """No-op for built-in backend."""
+        return None