softauth 0.1.0__py3-none-any.whl

softauth/database/models.py

@@ -0,0 +1,58 @@
+"""Default SQLAlchemy 2.0 user model.
+
+Developers can replace this model by implementing the UserStore interface.
+No framework imports; pure SQLAlchemy.
+"""
+
+from __future__ import annotations
+
+import uuid
+from datetime import datetime, timezone
+from typing import Any
+
+from sqlalchemy import Boolean, DateTime, String
+from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column
+
+
+class Base(DeclarativeBase):
+    pass
+
+
+class User(Base):
+    """Default user table created by ``auth.init_db()``."""
+
+    __tablename__ = "softauth_users"
+
+    id: Mapped[str] = mapped_column(
+        String(36),
+        primary_key=True,
+        default=lambda: str(uuid.uuid4()),
+    )
+    email: Mapped[str] = mapped_column(String(255), unique=True, nullable=False, index=True)
+    hashed_password: Mapped[str] = mapped_column(String(255), nullable=False)
+    is_active: Mapped[bool] = mapped_column(Boolean, default=True, nullable=False)
+    role: Mapped[str] = mapped_column(String(50), default="user", nullable=False)
+    created_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True),
+        default=lambda: datetime.now(timezone.utc),
+        nullable=False,
+    )
+    updated_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True),
+        default=lambda: datetime.now(timezone.utc),
+        onupdate=lambda: datetime.now(timezone.utc),
+        nullable=False,
+    )
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "id": self.id,
+            "email": self.email,
+            "is_active": self.is_active,
+            "role": self.role,
+            "created_at": self.created_at.isoformat(),
+            "updated_at": self.updated_at.isoformat(),
+        }
+
+    def __repr__(self) -> str:
+        return f"<User id={self.id!r} email={self.email!r} role={self.role!r}>"

softauth/database/repository.py

@@ -0,0 +1,46 @@
+"""UserRepository — synchronous CRUD over the default User model.
+
+No framework imports.  Accepts an open SQLAlchemy Session and performs
+operations within the caller's transaction boundary.
+"""
+
+from __future__ import annotations
+
+from typing import Optional
+
+from sqlalchemy.orm import Session
+
+from softauth.core.exceptions import UserAlreadyExistsError
+from softauth.database.models import User
+
+
+class UserRepository:
+    """Data-access object for the softauth_users table."""
+
+    def __init__(self, session: Session) -> None:
+        self._s = session
+
+    def get_by_id(self, user_id: str) -> Optional[User]:
+        return self._s.get(User, user_id)
+
+    def get_by_email(self, email: str) -> Optional[User]:
+        return self._s.query(User).filter(User.email == email).first()
+
+    def create(self, email: str, hashed_password: str, role: str = "user") -> User:
+        if self.get_by_email(email) is not None:
+            raise UserAlreadyExistsError(f"A user with email '{email}' already exists.")
+        user = User(email=email, hashed_password=hashed_password, role=role)
+        self._s.add(user)
+        self._s.flush()  # populate user.id before the context manager commits
+        return user
+
+    def update(self, user: User) -> User:
+        self._s.add(user)
+        return user
+
+    def deactivate(self, user_id: str) -> Optional[User]:
+        user = self.get_by_id(user_id)
+        if user:
+            user.is_active = False
+            self._s.add(user)
+        return user

softauth/database/session.py

@@ -0,0 +1,66 @@
+"""SQLAlchemy session factory.
+
+Wraps engine + SessionLocal into a single injectable object.
+No framework imports.
+"""
+
+from __future__ import annotations
+
+from contextlib import contextmanager
+from typing import Generator
+
+from sqlalchemy import create_engine
+from sqlalchemy.orm import Session, sessionmaker
+from sqlalchemy.pool import StaticPool
+
+from softauth.database.models import Base
+
+
+class DatabaseSession:
+    """Thin wrapper around an SQLAlchemy engine and session factory.
+
+    ``expire_on_commit=False`` is intentional: detached User objects returned
+    from session contexts remain usable (all columns already loaded in memory).
+
+    For ``sqlite:///:memory:``, ``StaticPool`` is used so all connections share
+    the same in-memory database — essential for testing in threaded environments
+    such as FastAPI's TestClient.
+    """
+
+    def __init__(self, database_url: str) -> None:
+        connect_args: dict[str, object] = {}
+        kwargs: dict[str, object] = {}
+
+        if database_url.startswith("sqlite"):
+            connect_args["check_same_thread"] = False
+            if ":memory:" in database_url:
+                kwargs["poolclass"] = StaticPool
+
+        self._engine = create_engine(database_url, connect_args=connect_args, **kwargs)  # type: ignore[arg-type]
+        self._factory = sessionmaker(
+            bind=self._engine,
+            autocommit=False,
+            autoflush=False,
+            expire_on_commit=False,
+        )
+
+    def create_tables(self) -> None:
+        """Create all softauth tables (idempotent)."""
+        Base.metadata.create_all(self._engine)
+
+    def drop_tables(self) -> None:
+        """Drop all softauth tables.  Useful in tests."""
+        Base.metadata.drop_all(self._engine)
+
+    @contextmanager
+    def session(self) -> Generator[Session, None, None]:
+        """Yield a transactional session; commit on success, rollback on error."""
+        s = self._factory()
+        try:
+            yield s
+            s.commit()
+        except Exception:
+            s.rollback()
+            raise
+        finally:
+            s.close()

softauth/django/__init__.py

@@ -0,0 +1,3 @@
+from softauth.django.adapter import DjangoAdapter
+
+__all__ = ["DjangoAdapter"]

softauth/django/adapter.py

@@ -0,0 +1,77 @@
+"""Django adapter — implements BaseAdapter for Django applications."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, Callable
+
+from softauth.core.config import SoftAuthConfig
+from softauth.interfaces.adapter import BaseAdapter
+
+if TYPE_CHECKING:
+    from softauth.core.auth import SoftAuth
+
+
+class DjangoAdapter(BaseAdapter):
+    """Wires SoftAuth into a Django application.
+
+    Responsibilities:
+    - Configures ``softauth.django.middleware.SoftAuthMiddleware`` via a
+      module-level singleton (called in ``on_startup()``).
+    - Appends auto-generated auth URL patterns to the provided ``urlpatterns``
+      list in ``init_app(urlpatterns)``.
+    - Exposes ``login_required``, ``admin_required``, and ``require_role()``
+      as standard Django view decorators.
+
+    Usage::
+
+        # settings.py
+        MIDDLEWARE = [
+            ...
+            "softauth.django.middleware.SoftAuthMiddleware",
+        ]
+
+        # urls.py
+        urlpatterns = []
+        auth.init_app(urlpatterns)   # appends /auth/* patterns
+    """
+
+    def __init__(self, auth: "SoftAuth", config: SoftAuthConfig) -> None:
+        self._auth = auth
+        self._config = config
+
+        from softauth.django.decorators import DecoratorFactory
+        self._dec = DecoratorFactory(auth, config)
+
+    def on_startup(self) -> None:
+        """Configure the middleware singleton with this adapter's JWT handler."""
+        from softauth.django import middleware as mw
+        mw.configure(self._auth.jwt)
+
+    def init_app(self, urlpatterns: Any) -> None:
+        """Append softauth URL patterns to *urlpatterns* (a Django ``urlpatterns`` list)."""
+        from softauth.django.urls import create_auth_urlpatterns
+        urlpatterns += create_auth_urlpatterns(self._auth, self._config)
+
+    # ── BaseAdapter ────────────────────────────────────────────────────────────
+
+    def get_current_user_dependency(self) -> Callable[..., Any]:
+        return self._dec.login_required
+
+    def get_current_admin_dependency(self) -> Callable[..., Any]:
+        return self._dec.admin_required
+
+    def get_require_role_dependency(self, role: str) -> Callable[..., Any]:
+        return self._dec.require_role(role)
+
+    # ── Shortcut properties used by SoftAuth ───────────────────────────────────
+
+    @property
+    def login_required(self) -> Callable[..., Any]:
+        return self._dec.login_required
+
+    @property
+    def admin_required(self) -> Callable[..., Any]:
+        return self._dec.admin_required
+
+    def require_role(self, role: str) -> Callable[..., Any]:
+        return self._dec.require_role(role)

softauth/django/decorators.py

@@ -0,0 +1,68 @@
+"""Django decorators: @login_required, @admin_required, @require_role."""
+
+from __future__ import annotations
+
+from functools import wraps
+from typing import TYPE_CHECKING, Any, Callable
+
+from django.http import JsonResponse
+
+from softauth.core.config import SoftAuthConfig
+
+if TYPE_CHECKING:
+    from softauth.core.auth import SoftAuth
+
+
+class DecoratorFactory:
+    """Builds Django view decorators that validate the JWT-populated request attributes."""
+
+    def __init__(self, auth: "SoftAuth", config: SoftAuthConfig) -> None:
+        self._auth = auth
+        self._config = config
+
+    def _load_user(self, request: Any) -> Any:
+        user_id = getattr(request, "softauth_user_id", None)
+        if not user_id:
+            return None
+        with self._auth._db.session() as s:
+            from softauth.database.repository import UserRepository
+            return UserRepository(s).get_by_id(user_id)
+
+    def login_required(self, fn: Callable[..., Any]) -> Callable[..., Any]:
+        """Require any authenticated active user."""
+        @wraps(fn)
+        def _wrapper(request: Any, *args: Any, **kwargs: Any) -> Any:
+            user = self._load_user(request)
+            if user is None or not user.is_active:
+                return JsonResponse({"error": "Authentication required"}, status=401)
+            request.softauth_user = user
+            return fn(request, *args, **kwargs)
+        return _wrapper
+
+    def admin_required(self, fn: Callable[..., Any]) -> Callable[..., Any]:
+        """Require an authenticated user with role == 'admin'."""
+        @wraps(fn)
+        def _wrapper(request: Any, *args: Any, **kwargs: Any) -> Any:
+            user = self._load_user(request)
+            if user is None or not user.is_active:
+                return JsonResponse({"error": "Authentication required"}, status=401)
+            if user.role != "admin":
+                return JsonResponse({"error": "Admin role required"}, status=403)
+            request.softauth_user = user
+            return fn(request, *args, **kwargs)
+        return _wrapper
+
+    def require_role(self, role: str) -> Callable[[Callable[..., Any]], Callable[..., Any]]:
+        """Require an authenticated user with ``role`` (admin is always allowed)."""
+        def _decorator(fn: Callable[..., Any]) -> Callable[..., Any]:
+            @wraps(fn)
+            def _wrapper(request: Any, *args: Any, **kwargs: Any) -> Any:
+                user = self._load_user(request)
+                if user is None or not user.is_active:
+                    return JsonResponse({"error": "Authentication required"}, status=401)
+                if user.role not in (role, "admin"):
+                    return JsonResponse({"error": f"Role '{role}' required"}, status=403)
+                request.softauth_user = user
+                return fn(request, *args, **kwargs)
+            return _wrapper
+        return _decorator

softauth/django/middleware.py

@@ -0,0 +1,59 @@
+"""Django middleware: populates request.softauth_* from JWT on every request.
+
+Add to Django settings:
+    MIDDLEWARE = [
+        ...
+        "softauth.django.middleware.SoftAuthMiddleware",
+    ]
+
+The middleware reads the jwt_handler configured by DjangoAdapter.on_startup().
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, Callable, Optional
+
+from softauth.core.exceptions import TokenError
+
+if TYPE_CHECKING:
+    from softauth.jwt.handler import JWTHandler
+
+_jwt_handler: Optional["JWTHandler"] = None
+
+
+def configure(jwt_handler: "JWTHandler") -> None:
+    """Register the JWTHandler used by SoftAuthMiddleware. Called by DjangoAdapter."""
+    global _jwt_handler
+    _jwt_handler = jwt_handler
+
+
+class SoftAuthMiddleware:
+    """Parses JWT from Authorization header and populates request.softauth_* attributes.
+
+    Sets on every request (regardless of whether a token is present):
+        request.softauth_user_id   — str | None
+        request.softauth_role      — str | None
+        request.softauth_payload   — dict | None
+    """
+
+    def __init__(self, get_response: Callable[..., Any]) -> None:
+        self.get_response = get_response
+
+    def __call__(self, request: Any) -> Any:
+        request.softauth_user_id = None
+        request.softauth_role = None
+        request.softauth_payload = None
+
+        if _jwt_handler is not None:
+            auth_header: str = request.META.get("HTTP_AUTHORIZATION", "")
+            if auth_header:
+                try:
+                    token = _jwt_handler.extract_token_from_header(auth_header)
+                    payload = _jwt_handler.decode_token(token)
+                    request.softauth_user_id = payload.get("sub")
+                    request.softauth_role = payload.get("role")
+                    request.softauth_payload = payload
+                except TokenError:
+                    pass
+
+        return self.get_response(request)

softauth/django/urls.py

@@ -0,0 +1,36 @@
+"""URL pattern factory for softauth's Django auth endpoints.
+
+Usage in your urls.py:
+    from django.urls import path, include
+    from softauth.django.urls import create_auth_urlpatterns
+
+    urlpatterns = [
+        # ... your routes
+    ] + create_auth_urlpatterns(auth, auth.config)
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from softauth.core.config import SoftAuthConfig
+from softauth.django.views import create_auth_views
+
+if TYPE_CHECKING:
+    from softauth.core.auth import SoftAuth
+
+
+def create_auth_urlpatterns(auth: "SoftAuth", config: SoftAuthConfig) -> list[Any]:
+    """Return Django URL patterns for all auth endpoints."""
+    from django.urls import path
+
+    views = create_auth_views(auth, config)
+    prefix = config.auth_prefix.strip("/")
+
+    return [
+        path(f"{prefix}/register/", views["register"], name="softauth-register"),
+        path(f"{prefix}/login/", views["login"], name="softauth-login"),
+        path(f"{prefix}/refresh/", views["refresh"], name="softauth-refresh"),
+        path(f"{prefix}/me/", views["me"], name="softauth-me"),
+        path(f"{prefix}/logout/", views["logout"], name="softauth-logout"),
+    ]

softauth/django/views.py

@@ -0,0 +1,139 @@
+"""Django view functions for the auto-generated auth endpoints.
+
+Provides: POST /register  POST /login  POST /refresh  GET /me  POST /logout
+"""
+
+from __future__ import annotations
+
+import json
+from typing import TYPE_CHECKING, Any
+
+from django.http import JsonResponse
+from django.views.decorators.csrf import csrf_exempt
+
+from softauth.core.config import SoftAuthConfig
+from softauth.core.exceptions import InvalidTokenError, TokenExpiredError, UserAlreadyExistsError
+
+if TYPE_CHECKING:
+    from softauth.core.auth import SoftAuth
+
+
+def create_auth_views(auth: "SoftAuth", config: SoftAuthConfig) -> dict[str, Any]:
+    """Return a dict of Django view callables, one per auth endpoint."""
+
+    def _body(request: Any) -> dict[str, Any]:
+        try:
+            return json.loads(request.body or b"{}") or {}
+        except (json.JSONDecodeError, ValueError):
+            return {}
+
+    @csrf_exempt
+    def register(request: Any) -> JsonResponse:
+        if request.method != "POST":
+            return JsonResponse({"error": "Method not allowed"}, status=405)
+        body = _body(request)
+        email: str = body.get("email", "")
+        password: str = body.get("password", "")
+        role: str = body.get("role", "user")
+
+        if not email or not password:
+            return JsonResponse({"error": "email and password are required"}, status=400)
+
+        try:
+            with auth._db.session() as s:
+                from softauth.database.repository import UserRepository
+                user = UserRepository(s).create(
+                    email=email,
+                    hashed_password=auth.passwords.hash_password(password),
+                    role=role,
+                )
+            return JsonResponse({"message": "User registered successfully", "id": user.id}, status=201)
+        except UserAlreadyExistsError as exc:
+            return JsonResponse({"error": str(exc)}, status=409)
+
+    @csrf_exempt
+    def login(request: Any) -> JsonResponse:
+        if request.method != "POST":
+            return JsonResponse({"error": "Method not allowed"}, status=405)
+        body = _body(request)
+        email: str = body.get("email", "")
+        password: str = body.get("password", "")
+
+        with auth._db.session() as s:
+            from softauth.database.repository import UserRepository
+            user = UserRepository(s).get_by_email(email)
+
+        if user is None or not auth.passwords.verify_password(password, user.hashed_password):
+            return JsonResponse({"error": "Invalid credentials"}, status=401)
+        if not user.is_active:
+            return JsonResponse({"error": "Inactive user"}, status=400)
+
+        access_token = auth.jwt.create_access_token(subject=user.id, role=user.role)
+        refresh_token = auth.jwt.create_refresh_token(subject=user.id)
+
+        return JsonResponse({
+            "access_token": access_token,
+            "refresh_token": refresh_token,
+            "token_type": "bearer",
+            "expires_in": config.access_expiry_minutes * 60,
+        })
+
+    @csrf_exempt
+    def refresh(request: Any) -> JsonResponse:
+        if request.method != "POST":
+            return JsonResponse({"error": "Method not allowed"}, status=405)
+        body = _body(request)
+        token: str = body.get("refresh_token", "")
+
+        try:
+            payload = auth.jwt.decode_token(token)
+        except TokenExpiredError:
+            return JsonResponse({"error": "Refresh token expired"}, status=401)
+        except InvalidTokenError:
+            return JsonResponse({"error": "Invalid refresh token"}, status=401)
+
+        if payload.get("type") != "refresh":
+            return JsonResponse({"error": "Not a refresh token"}, status=401)
+
+        user_id: str = payload["sub"]
+        with auth._db.session() as s:
+            from softauth.database.repository import UserRepository
+            user = UserRepository(s).get_by_id(user_id)
+
+        if user is None or not user.is_active:
+            return JsonResponse({"error": "User not found or inactive"}, status=401)
+
+        new_token = auth.jwt.create_access_token(subject=user_id, role=user.role)
+        return JsonResponse({
+            "access_token": new_token,
+            "token_type": "bearer",
+            "expires_in": config.access_expiry_minutes * 60,
+        })
+
+    @csrf_exempt
+    def me(request: Any) -> JsonResponse:
+        if request.method != "GET":
+            return JsonResponse({"error": "Method not allowed"}, status=405)
+        user_id = getattr(request, "softauth_user_id", None)
+        if not user_id:
+            return JsonResponse({"error": "Authentication required"}, status=401)
+
+        with auth._db.session() as s:
+            from softauth.database.repository import UserRepository
+            user = UserRepository(s).get_by_id(user_id)
+
+        if user is None:
+            return JsonResponse({"error": "User not found"}, status=404)
+        return JsonResponse(user.to_dict())
+
+    @csrf_exempt
+    def logout(request: Any) -> JsonResponse:
+        return JsonResponse({"message": "Logged out successfully"})
+
+    return {
+        "register": register,
+        "login": login,
+        "refresh": refresh,
+        "me": me,
+        "logout": logout,
+    }

softauth/fastapi/__init__.py

@@ -0,0 +1,6 @@
+from softauth.fastapi.adapter import FastAPIAdapter
+from softauth.fastapi.dependencies import DependencyFactory
+from softauth.fastapi.middleware import JWTMiddleware
+from softauth.fastapi.routes import create_auth_router
+
+__all__ = ["FastAPIAdapter", "DependencyFactory", "JWTMiddleware", "create_auth_router"]

softauth/fastapi/adapter.py

@@ -0,0 +1,55 @@
+"""FastAPI adapter — implements BaseAdapter for FastAPI applications."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, Callable
+
+from softauth.core.config import SoftAuthConfig
+from softauth.interfaces.adapter import BaseAdapter
+
+if TYPE_CHECKING:
+    from fastapi import FastAPI
+    from softauth.core.auth import SoftAuth
+
+
+class FastAPIAdapter(BaseAdapter):
+    """Wires SoftAuth into a FastAPI application.
+
+    Responsibilities:
+    - Registers ``JWTMiddleware`` so ``request.state.user_*`` is always set.
+    - Mounts the auto-generated auth router under ``config.auth_prefix``.
+    - Exposes ``current_user``, ``current_admin``, and ``require_role()``
+      as FastAPI-native ``Depends()``-compatible callables.
+    """
+
+    def __init__(self, auth: "SoftAuth", config: SoftAuthConfig) -> None:
+        self._auth = auth
+        self._config = config
+
+        from softauth.fastapi.dependencies import DependencyFactory
+        self._deps = DependencyFactory(auth, config)
+
+    def init_app(self, app: "FastAPI") -> None:
+        from softauth.fastapi.middleware import JWTMiddleware
+        from softauth.fastapi.routes import create_auth_router
+
+        app.add_middleware(
+            JWTMiddleware,
+            config=self._config,
+            jwt_handler=self._auth.jwt,
+        )
+        router = create_auth_router(self._auth, self._config, self._deps)
+        app.include_router(
+            router,
+            prefix=self._config.auth_prefix,
+            tags=["Authentication"],
+        )
+
+    def get_current_user_dependency(self) -> Callable[..., Any]:
+        return self._deps.current_user
+
+    def get_current_admin_dependency(self) -> Callable[..., Any]:
+        return self._deps.current_admin
+
+    def get_require_role_dependency(self, role: str) -> Callable[..., Any]:
+        return self._deps.require_role(role)