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

fastapi_admin_kit/auth/models.py

@@ -0,0 +1,246 @@
+"""SQLAlchemy models for admin auth: roles, users, permissions."""
+
+from __future__ import annotations
+
+from sqlalchemy import (
+    Boolean,
+    Column,
+    DateTime,
+    ForeignKey,
+    Integer,
+    String,
+    Table,
+    Text,
+    UniqueConstraint,
+)
+from sqlalchemy.orm import relationship
+from sqlalchemy.sql import func
+
+from fastapi_admin_kit.modeladmin import ModelAdmin
+from fastapi_admin_kit.models.base import Base
+
+# Junction table — no ORM model needed
+admin_user_roles = Table(
+    "admin_user_roles",
+    Base.metadata,
+    Column(
+        "user_id",
+        Integer,
+        ForeignKey("admin_users.id", ondelete="CASCADE"),
+        primary_key=True,
+    ),
+    Column(
+        "role_id",
+        Integer,
+        ForeignKey("admin_roles.id", ondelete="CASCADE"),
+        primary_key=True,
+    ),
+)
+
+
+class AdminRole(Base):
+    __tablename__ = "admin_roles"
+
+    id = Column(Integer, primary_key=True)
+    name = Column(String(100), unique=True, nullable=False)
+    description = Column(Text)
+    created_at = Column(DateTime(timezone=True), server_default=func.now())
+
+    users = relationship(
+        "AdminUser", secondary=admin_user_roles, back_populates="roles"
+    )
+    permissions = relationship(
+        "AdminPermission", back_populates="role", cascade="all, delete-orphan"
+    )
+
+    def __str__(self) -> str:
+        return str(self.name)
+
+    def __repr__(self) -> str:
+        return f"<AdminRole {self.name!r}>"
+
+
+class AdminUser(Base):
+    __tablename__ = "admin_users"
+
+    id = Column(Integer, primary_key=True)
+    email = Column(String(255), unique=True, nullable=False)
+    hashed_password = Column(String(255), nullable=False)
+    full_name = Column(String(255))
+    is_superuser = Column(Boolean, default=False)
+    is_active = Column(Boolean, default=True)
+    last_login = Column(DateTime(timezone=True))
+    created_at = Column(DateTime(timezone=True), server_default=func.now())
+    password_changed_at = Column(DateTime(timezone=True), nullable=True)
+
+    # Many-to-many roles
+    roles = relationship(
+        "AdminRole", secondary=admin_user_roles, back_populates="users"
+    )
+    # Direct permission overrides
+    direct_permissions = relationship(
+        "AdminUserPermission",
+        back_populates="user",
+        cascade="all, delete-orphan",
+    )
+    refresh_tokens = relationship(
+        "AdminRefreshToken", back_populates="user", cascade="all, delete-orphan"
+    )
+    totp = relationship(
+        "AdminUserTOTP",
+        back_populates="user",
+        uselist=False,
+        cascade="all, delete-orphan",
+    )
+
+    @property
+    def role_ids(self) -> list[int]:
+        return [r.id for r in self.roles]
+
+    def __str__(self) -> str:
+        return str(self.email)
+
+    def __repr__(self) -> str:
+        return f"<AdminUser {self.email!r}>"
+
+
+class AdminPermission(Base):
+    """Permission matrix per role per model."""
+
+    __tablename__ = "admin_permissions"
+    __table_args__ = (
+        UniqueConstraint(
+            "role_id", "table_name", name="uq_admin_perm_role_table"
+        ),
+    )
+
+    id = Column(Integer, primary_key=True)
+    role_id = Column(
+        Integer,
+        ForeignKey("admin_roles.id", ondelete="CASCADE"),
+        nullable=False,
+    )
+    table_name = Column(String(255), nullable=False)
+    can_view = Column(Boolean, default=False)
+    can_create = Column(Boolean, default=False)
+    can_edit = Column(Boolean, default=False)
+    can_delete = Column(Boolean, default=False)
+
+    role = relationship("AdminRole", back_populates="permissions")
+
+    def __str__(self) -> str:
+        return f"{self.table_name} (role {self.role_id})"
+
+    def __repr__(self) -> str:
+        return (
+            f"<AdminPermission role={self.role_id} table={self.table_name!r}>"
+        )
+
+
+class AdminUserPermission(Base):
+    """Direct per-user permission overrides — merged with role permissions."""
+
+    __tablename__ = "admin_user_permissions"
+    __table_args__ = (
+        UniqueConstraint(
+            "user_id", "table_name", name="uq_admin_user_perm_user_table"
+        ),
+    )
+
+    id = Column(Integer, primary_key=True)
+    user_id = Column(
+        Integer,
+        ForeignKey("admin_users.id", ondelete="CASCADE"),
+        nullable=False,
+    )
+    table_name = Column(String(255), nullable=False)
+    can_view = Column(Boolean, default=False)
+    can_create = Column(Boolean, default=False)
+    can_edit = Column(Boolean, default=False)
+    can_delete = Column(Boolean, default=False)
+
+    user = relationship("AdminUser", back_populates="direct_permissions")
+
+    def __str__(self) -> str:
+        return f"{self.table_name} (user {self.user_id})"
+
+    def __repr__(self) -> str:
+        return f"<AdminUserPermission user={self.user_id} table={self.table_name!r}>"
+
+
+class AdminRefreshToken(Base):
+    __tablename__ = "admin_refresh_tokens"
+
+    id = Column(Integer, primary_key=True)
+    user_id = Column(
+        Integer,
+        ForeignKey("admin_users.id", ondelete="CASCADE"),
+        nullable=False,
+    )
+    token_hash = Column(String(64), nullable=False, index=True)
+    expires_at = Column(DateTime(timezone=True), nullable=False)
+    created_at = Column(DateTime(timezone=True), server_default=func.now())
+    revoked_at = Column(DateTime(timezone=True), nullable=True)
+
+    user = relationship("AdminUser", back_populates="refresh_tokens")
+
+    __table_args__ = (
+        UniqueConstraint(
+            "user_id", "token_hash", name="uq_admin_refresh_token"
+        ),
+    )
+
+    def __str__(self) -> str:
+        return f"Token {self.token_hash[:8]}..."
+
+    def __repr__(self) -> str:
+        return f"<AdminRefreshToken user={self.user_id}>"
+
+
+class AdminRefreshTokenAdmin(ModelAdmin):
+    exclude = ["user"]
+
+
+class AdminUserTOTP(Base):
+    __tablename__ = "admin_user_totp"
+
+    id = Column(Integer, primary_key=True)
+    user_id = Column(
+        Integer,
+        ForeignKey("admin_users.id", ondelete="CASCADE"),
+        unique=True,
+        nullable=False,
+    )
+    secret_key = Column(String(255), nullable=False)
+    enabled = Column(Boolean, default=False)
+    backup_codes = Column(Text, nullable=True)
+    created_at = Column(DateTime(timezone=True), server_default=func.now())
+
+    user = relationship("AdminUser", back_populates="totp")
+
+    def __str__(self) -> str:
+        return f"TOTP for user {self.user_id}"
+
+    def __repr__(self) -> str:
+        return f"<AdminUserTOTP user={self.user_id}>"
+
+
+class AdminLoginAttempt(Base):
+    __tablename__ = "admin_login_attempts"
+
+    id = Column(Integer, primary_key=True)
+    email = Column(String(255), nullable=False, index=True)
+    ip_address = Column(String(45), nullable=False)
+    user_agent = Column(String(512), nullable=True)
+    success = Column(Boolean, default=False)
+    timestamp = Column(DateTime(timezone=True), server_default=func.now())
+
+    __table_args__ = (UniqueConstraint("id", name="uq_admin_login_attempt_id"),)
+
+    def __str__(self) -> str:
+        return f"{self.email} - {'success' if self.success else 'failed'}"
+
+    def __repr__(self) -> str:
+        return (
+            f"<AdminLoginAttempt email={self.email!r} success={self.success}>"
+        )

fastapi_admin_kit/auth/password.py

@@ -0,0 +1,35 @@
+"""Password strength validation."""
+
+from __future__ import annotations
+
+import re
+
+
+def validate_password_strength(
+    password: str,
+    *,
+    min_length: int = 12,
+    require_uppercase: bool = True,
+    require_lowercase: bool = True,
+    require_digit: bool = True,
+    require_special: bool = True,
+) -> list[str]:
+    """Validate password strength. Returns a list of error messages (empty = valid)."""
+    errors: list[str] = []
+
+    if len(password) < min_length:
+        errors.append(f"Password must be at least {min_length} characters long.")
+
+    if require_uppercase and not re.search(r"[A-Z]", password):
+        errors.append("Password must contain at least one uppercase letter.")
+
+    if require_lowercase and not re.search(r"[a-z]", password):
+        errors.append("Password must contain at least one lowercase letter.")
+
+    if require_digit and not re.search(r"\d", password):
+        errors.append("Password must contain at least one digit.")
+
+    if require_special and not re.search(r"[!@#$%^&*()_+\-=\[\]{};':\"\\|,.<>\/?]", password):
+        errors.append("Password must contain at least one special character.")
+
+    return errors

fastapi_admin_kit/auth/permissions.py

@@ -0,0 +1,205 @@
+"""RBAC permission checker — per-request, with in-memory caching."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from fastapi_admin_kit.auth.models import AdminPermission, AdminUserPermission
+from fastapi_admin_kit.types import PermissionSet
+
+if TYPE_CHECKING:
+    from sqlalchemy.ext.asyncio import AsyncSession
+
+    from fastapi_admin_kit.auth.protocol import AdminUserProtocol
+
+
+class PermissionChecker:
+    """Per-request permission checker.
+
+    Instantiated once per request via ``Depends(get_permission_checker)``.
+    Caches permission results in-memory for the lifetime of the request.
+
+    Merges permissions from:
+    1. All assigned roles (M2M via admin_user_roles)
+    2. Direct per-user overrides (AdminUserPermission)
+
+    Role permissions are OR'd together, then direct overrides are OR'd on top.
+    """
+
+    def __init__(
+        self,
+        session: AsyncSession,
+        user: AdminUserProtocol,
+        *,
+        user_snapshot: dict[str, object] | None = None,
+    ) -> None:
+        self.session = session
+        self.user = user
+        snap = user_snapshot or {}
+        self._is_superuser: bool = (
+            bool(snap["is_superuser"]) if "is_superuser" in snap else bool(user.is_superuser)
+        )
+        self._role_ids: list[int] = (
+            snap["role_ids"] if "role_ids" in snap else getattr(user, "role_ids", [])
+        )
+        self._user_id: int | str | None = (
+            snap.get("id") if snap else getattr(user, "id", None)
+        )
+        self._role_cache: dict[str, PermissionSet | None] | None = None
+        self._direct_cache: dict[str, PermissionSet | None] | None = None
+        self._cache: dict[tuple[str, str], bool] = {}
+        self._field_cache: dict[tuple[str, str], set[str] | None] = {}
+
+    async def _load_role_permissions(self) -> dict[str, PermissionSet | None]:
+        """Load and cache all role-based permissions, merged with OR logic."""
+        if self._role_cache is not None:
+            return self._role_cache
+
+        self._role_cache = {}
+        if not self._role_ids:
+            return self._role_cache
+
+        from sqlalchemy import select
+
+        result = await self.session.execute(
+            select(AdminPermission).where(
+                AdminPermission.role_id.in_(self._role_ids)
+            )
+        )
+        for perm in result.scalars():
+            table = perm.table_name
+            if table not in self._role_cache:
+                self._role_cache[table] = PermissionSet()
+            ps = self._role_cache[table]
+            if perm.can_view:
+                ps.can_view = True
+            if perm.can_create:
+                ps.can_create = True
+            if perm.can_edit:
+                ps.can_edit = True
+            if perm.can_delete:
+                ps.can_delete = True
+
+        return self._role_cache
+
+    async def _load_direct_permissions(self) -> dict[str, PermissionSet | None]:
+        """Load and cache direct per-user permission overrides."""
+        if self._direct_cache is not None:
+            return self._direct_cache
+
+        self._direct_cache = {}
+        if self._user_id is None:
+            return self._direct_cache
+
+        from sqlalchemy import select
+
+        result = await self.session.execute(
+            select(AdminUserPermission).where(
+                AdminUserPermission.user_id == self._user_id
+            )
+        )
+        for perm in result.scalars():
+            table = perm.table_name
+            if table not in self._direct_cache:
+                self._direct_cache[table] = PermissionSet()
+            ps = self._direct_cache[table]
+            if perm.can_view:
+                ps.can_view = True
+            if perm.can_create:
+                ps.can_create = True
+            if perm.can_edit:
+                ps.can_edit = True
+            if perm.can_delete:
+                ps.can_delete = True
+
+        return self._direct_cache
+
+    async def _get_merged_permission(self, table_name: str, action: str) -> bool:
+        """Get merged permission for a table+action across roles and direct overrides."""
+        role_perms = await self._load_role_permissions()
+        direct_perms = await self._load_direct_permissions()
+
+        attr = f"can_{action}"
+
+        role_ps = role_perms.get(table_name)
+        direct_ps = direct_perms.get(table_name)
+
+        role_val = getattr(role_ps, attr, False) if role_ps else False
+        direct_val = getattr(direct_ps, attr, False) if direct_ps else False
+
+        return role_val or direct_val
+
+    async def has_permission(self, table_name: str, action: str) -> bool:
+        """Return True if the current user may perform *action* on *table_name*.
+
+        Actions: ``"view"`` | ``"create"`` | ``"edit"`` | ``"delete"``
+
+        Superusers always return True. Results are cached per-request.
+        """
+        if self._is_superuser:
+            return True
+
+        cache_key = (table_name, action)
+        if cache_key in self._cache:
+            return self._cache[cache_key]
+
+        result_bool = await self._get_merged_permission(table_name, action)
+        self._cache[cache_key] = result_bool
+        return result_bool
+
+    async def get_allowed_fields(self, table_name: str, mode: str) -> set[str] | None:
+        """Return the set of field names the user may access, or ``None``.
+
+        mode: ``"view"`` | ``"edit"``
+
+        Semantics:
+        - ``None`` → no field-level restrictions exist → all fields allowed.
+        - Empty ``set()`` → restriction rows exist but none grant access → no fields.
+        - Non-empty ``set()`` → only those field names are permitted.
+        """
+        if self._is_superuser:
+            return None
+
+        cache_key = (table_name, mode)
+        if cache_key in self._field_cache:
+            return self._field_cache[cache_key]
+
+        # No role and no direct permissions → all fields restricted
+        if not self._role_ids and self._user_id is None:
+            self._field_cache[cache_key] = set()
+            return set()
+
+        # No field-level restrictions in this system anymore
+        self._field_cache[cache_key] = None
+        return None
+
+    def permission_set(self, table_name: str) -> PermissionSet:
+        """Return a :class:`PermissionSet` for convenient template / UI use.
+
+        Note: This is a sync convenience wrapper. For async contexts,
+        use the individual async methods directly.
+        """
+        if self._is_superuser:
+            return PermissionSet(
+                can_view=True,
+                can_create=True,
+                can_edit=True,
+                can_delete=True,
+            )
+        return PermissionSet(
+            can_view=self._cache.get((table_name, "view"), False),
+            can_create=self._cache.get((table_name, "create"), False),
+            can_edit=self._cache.get((table_name, "edit"), False),
+            can_delete=self._cache.get((table_name, "delete"), False),
+        )
+
+    async def load_permissions(self, table_name: str) -> PermissionSet:
+        """Async method to load and cache all permissions for a table.
+
+        Call this before using ``permission_set()`` to ensure the cache is populated.
+        """
+        await self.has_permission(table_name, "view")
+        await self.has_permission(table_name, "create")
+        await self.has_permission(table_name, "edit")
+        await self.has_permission(table_name, "delete")
+        return self.permission_set(table_name)

fastapi_admin_kit/auth/protocol.py

@@ -0,0 +1,22 @@
+"""Protocol for user models that can be used as the admin auth model."""
+
+from __future__ import annotations
+
+from typing import Protocol, runtime_checkable
+
+
+@runtime_checkable
+class AdminUserProtocol(Protocol):
+    """
+    Any user model passed as auth_model= must satisfy this interface.
+    These are the only attributes the admin framework reads from the user object.
+    """
+
+    id: int | str  # primary key (any type)
+    email: str  # used for audit log denormalization
+    is_active: bool  # inactive users are refused login
+    is_superuser: bool  # bypasses all permission checks if True
+
+    # Many-to-many roles — the admin reads this to look up permissions.
+    # Must be an iterable of role objects, each with an `id` attribute.
+    roles: list  # list of AdminRole objects (or compatible)

fastapi_admin_kit/auth/ratelimit.py

@@ -0,0 +1,88 @@
+"""In-memory sliding window rate limiter — no external dependencies."""
+
+from __future__ import annotations
+
+import time
+from collections import defaultdict
+from threading import Lock
+
+from fastapi import HTTPException, Request
+
+
+class RateLimiter:
+    """Sliding-window rate limiter.
+
+    Tracks request timestamps per key and rejects when the count exceeds
+    ``max_attempts`` within ``window_seconds``.
+    """
+
+    def __init__(
+        self,
+        max_attempts: int = 5,
+        window_seconds: int = 900,
+    ) -> None:
+        self.max_attempts = max_attempts
+        self.window_seconds = window_seconds
+        self._attempts: dict[str, list[float]] = defaultdict(list)
+        self._lock = Lock()
+
+    def _cleanup(self, key: str, now: float) -> None:
+        """Remove expired entries for *key*."""
+        cutoff = now - self.window_seconds
+        attempts = self._attempts[key]
+        self._attempts[key] = [t for t in attempts if t > cutoff]
+
+    def is_rate_limited(self, key: str) -> bool:
+        """Return True if *key* has exceeded the allowed attempts."""
+        now = time.monotonic()
+        with self._lock:
+            self._cleanup(key, now)
+            if len(self._attempts[key]) >= self.max_attempts:
+                return True
+            return False
+
+    def record_attempt(self, key: str) -> None:
+        """Record a request attempt for *key*."""
+        now = time.monotonic()
+        with self._lock:
+            self._cleanup(key, now)
+            self._attempts[key].append(now)
+
+    def reset(self, key: str) -> None:
+        """Clear all attempts for *key* (e.g. on successful login)."""
+        with self._lock:
+            self._attempts.pop(key, None)
+
+    def remaining_seconds(self, key: str) -> int:
+        """Seconds until the oldest attempt in the window expires."""
+        now = time.monotonic()
+        with self._lock:
+            self._cleanup(key, now)
+            attempts = self._attempts[key]
+            if not attempts:
+                return 0
+            return max(0, int(self.window_seconds - (now - attempts[0])) + 1)
+
+
+def _client_ip(request: Request) -> str:
+    """Extract client IP, respecting X-Forwarded-For."""
+    forwarded = request.headers.get("x-forwarded-for")
+    if forwarded:
+        return forwarded.split(",")[0].strip()
+    if request.client:
+        return request.client.host
+    return "unknown"
+
+
+def check_rate_limit(
+    limiter: RateLimiter,
+    key: str,
+) -> None:
+    """Raise 429 if *key* is rate-limited."""
+    if limiter.is_rate_limited(key):
+        retry = limiter.remaining_seconds(key)
+        raise HTTPException(
+            status_code=429,
+            detail="Too many attempts. Please try again later.",
+            headers={"Retry-After": str(retry)},
+        )

fastapi_admin_kit/auth/router.py

@@ -0,0 +1,10 @@
+"""Auth router — mounts login/logout views."""
+
+from __future__ import annotations
+
+from fastapi import APIRouter
+
+from fastapi_admin_kit.auth import views
+
+router = APIRouter()
+router.include_router(views.router)

fastapi_admin_kit/auth/session.py

@@ -0,0 +1,79 @@
+"""Session backend — ABC + signed-cookie implementation."""
+
+from __future__ import annotations
+
+import time
+from abc import ABC, abstractmethod
+from typing import Any
+
+from itsdangerous import (
+    BadSignature,
+    SignatureExpired,
+    URLSafeTimedSerializer,
+)
+
+
+class SessionBackend(ABC):
+    """Abstract session backend — encode/decode session payloads."""
+
+    @abstractmethod
+    def encode(self, payload: dict[str, Any]) -> str:
+        """Sign *payload* and return a token string suitable for a cookie."""
+        ...
+
+    @abstractmethod
+    def decode(self, token: str | None) -> dict[str, Any] | None:
+        """Verify *token* and return the payload dict, or ``None`` if invalid/expired."""
+        ...
+
+
+class SignedCookieSessionBackend(SessionBackend):
+    """Session backend that signs a JSON payload using ``itsdangerous``.
+
+    The cookie value is a ``URLSafeTimedSerializer``-serialized string — the JSON
+    payload is base64-encoded so its output is safe for ``Cookie`` headers (unlike
+    raw JSON, which contains ``{``, ``}``, ``\"`` and other characters that break
+    the ``http.cookies.SimpleCookie`` parser).
+    """
+
+    COOKIE_NAME = "admin_session"
+
+    def __init__(
+        self,
+        secret_key: str,
+        session_ttl: int = 28800,
+        cookie_name: str = COOKIE_NAME,
+        secure: bool = False,
+    ) -> None:
+        self._secret_key = secret_key
+        self._serializer = URLSafeTimedSerializer(
+            secret_key, salt="admin-session"
+        )
+        self._session_ttl = session_ttl
+        self.cookie_name = cookie_name
+        self.secure = secure
+
+    @property
+    def secret_key(self) -> str:
+        """The signing key used by this backend.
+
+        Public accessor so CSRF / JWT signing can share the same key without
+        reaching into the (private) itsdangerous signer. Swapping the session
+        backend no longer silently breaks CSRF.
+        """
+        return self._secret_key
+
+    def encode(self, payload: dict[str, Any]) -> str:
+        """Sign *payload* and return the signed token."""
+        if "iat" not in payload:
+            payload["iat"] = time.time()
+        return self._serializer.dumps(payload)
+
+    def decode(self, token: str | None) -> dict[str, Any] | None:
+        """Verify *token* and return the decoded payload, or ``None``."""
+        if not token:
+            return None
+        try:
+            return self._serializer.loads(token, max_age=self._session_ttl)
+        except (BadSignature, SignatureExpired, ValueError):
+            return None