softauth 0.1.0__py3-none-any.whl

softauth/__init__.py

@@ -0,0 +1,73 @@
+"""softauth — Zero-setup JWT authentication for FastAPI and Flask.
+
+Quick start (FastAPI)::
+
+    from fastapi import FastAPI, Depends
+    from softauth import SoftAuth
+
+    auth = SoftAuth(secret_key="your-secret", framework="fastapi")
+    app = FastAPI()
+    auth.init_app(app)
+    auth.init_db()
+
+    @app.get("/me")
+    def me(user=Depends(auth.current_user)):
+        return user.to_dict()
+
+Quick start (Flask)::
+
+    from flask import Flask, g
+    from softauth import SoftAuth
+
+    auth = SoftAuth(secret_key="your-secret", framework="flask")
+    app = Flask(__name__)
+    auth.init_app(app)
+    auth.init_db()
+
+    @app.route("/me")
+    @auth.login_required
+    def me():
+        return g.user.to_dict()
+"""
+
+from softauth.core.auth import SoftAuth
+from softauth.core.config import SoftAuthConfig
+from softauth.core.exceptions import (
+    AdapterNotInitializedError,
+    AuthError,
+    ConfigurationError,
+    InactiveUserError,
+    InvalidCredentialsError,
+    InvalidTokenError,
+    PermissionDeniedError,
+    SoftAuthError,
+    TokenError,
+    TokenExpiredError,
+    TokenTypeMismatchError,
+    UserAlreadyExistsError,
+    UserNotFoundError,
+)
+from softauth.jwt.handler import JWTHandler
+from softauth.security.password import PasswordHandler
+
+__version__ = "0.1.0"
+__all__ = [
+    "SoftAuth",
+    "SoftAuthConfig",
+    "JWTHandler",
+    "PasswordHandler",
+    # Exceptions
+    "SoftAuthError",
+    "AuthError",
+    "TokenError",
+    "TokenExpiredError",
+    "InvalidTokenError",
+    "TokenTypeMismatchError",
+    "InvalidCredentialsError",
+    "InactiveUserError",
+    "UserNotFoundError",
+    "UserAlreadyExistsError",
+    "PermissionDeniedError",
+    "ConfigurationError",
+    "AdapterNotInitializedError",
+]

softauth/cli/__init__.py

@@ -0,0 +1,3 @@
+from softauth.cli.commands import app
+
+__all__ = ["app"]

softauth/cli/commands.py

@@ -0,0 +1,233 @@
+"""Typer CLI for softauth.
+
+Commands:
+    softauth init            — scaffold .env and auth/ directory
+    softauth setup fastapi   — generate a ready-to-run FastAPI main.py
+    softauth setup flask     — generate a ready-to-run Flask app.py
+    softauth secret          — print a cryptographically secure key
+"""
+
+from __future__ import annotations
+
+import secrets
+from pathlib import Path
+from typing import Optional
+
+import typer
+
+app = typer.Typer(
+    name="softauth",
+    help="softauth — zero-setup JWT authentication CLI",
+    add_completion=False,
+)
+
+setup_app = typer.Typer(help="Generate framework-specific boilerplate.")
+app.add_typer(setup_app, name="setup")
+
+
+# ── softauth init ──────────────────────────────────────────────────────────────
+
+@app.command()
+def init() -> None:
+    """Scaffold the auth/ directory and a .env file with a fresh secret key."""
+    auth_dir = Path("auth")
+    auth_dir.mkdir(exist_ok=True)
+    (auth_dir / "__init__.py").touch()
+
+    env_path = Path(".env")
+    if env_path.exists():
+        typer.echo(".env already exists — skipping.")
+    else:
+        secret = secrets.token_hex(32)
+        env_path.write_text(
+            f"# SoftAuth — do NOT commit this file\n"
+            f"SOFTAUTH_SECRET={secret}\n"
+            f"SOFTAUTH_DB_URL=sqlite:///auth.db\n"
+            f"SOFTAUTH_ALGORITHM=HS256\n",
+            encoding="utf-8",
+        )
+        typer.echo(f"Created .env with a fresh secret key.")
+
+    typer.echo(f"Initialised auth/ directory.")
+    typer.echo("Next steps:")
+    typer.echo("  softauth setup fastapi   (or flask)")
+    typer.echo("  python -m uvicorn main:app --reload")
+
+
+# ── softauth setup fastapi ─────────────────────────────────────────────────────
+
+@setup_app.command("fastapi")
+def setup_fastapi() -> None:
+    """Generate a ready-to-run FastAPI application with softauth wired in."""
+    target = Path("main.py")
+    if target.exists():
+        typer.echo("main.py already exists — skipping.")
+        raise typer.Exit()
+
+    target.write_text(
+        '''\
+from fastapi import FastAPI, Depends
+from softauth import SoftAuth
+from dotenv import load_dotenv
+import os
+
+load_dotenv()
+
+auth = SoftAuth(
+    secret_key=os.environ["SOFTAUTH_SECRET"],
+    framework="fastapi",
+    database_url=os.getenv("SOFTAUTH_DB_URL", "sqlite:///auth.db"),
+)
+
+app = FastAPI(title="My App")
+auth.init_app(app)
+auth.init_db()
+
+
+# ── Protected routes ──────────────────────────────────────────────────────────
+
+@app.get("/profile")
+def profile(user=Depends(auth.current_user)):
+    return user.to_dict()
+
+
+@app.get("/admin")
+def admin_dashboard(user=Depends(auth.current_admin)):
+    return {"message": f"Welcome, admin {user.email}"}
+
+
+@app.get("/manager")
+def manager_page(user=Depends(auth.require_role("manager"))):
+    return {"message": f"Welcome, manager {user.email}"}
+''',
+        encoding="utf-8",
+    )
+    typer.echo("Created main.py — run with:  uvicorn main:app --reload")
+
+
+# ── softauth setup flask ───────────────────────────────────────────────────────
+
+@setup_app.command("flask")
+def setup_flask() -> None:
+    """Generate a ready-to-run Flask application with softauth wired in."""
+    target = Path("app.py")
+    if target.exists():
+        typer.echo("app.py already exists — skipping.")
+        raise typer.Exit()
+
+    target.write_text(
+        '''\
+from flask import Flask, g, jsonify
+from softauth import SoftAuth
+from dotenv import load_dotenv
+import os
+
+load_dotenv()
+
+auth = SoftAuth(
+    secret_key=os.environ["SOFTAUTH_SECRET"],
+    framework="flask",
+    database_url=os.getenv("SOFTAUTH_DB_URL", "sqlite:///auth.db"),
+)
+
+app = Flask(__name__)
+auth.init_app(app)
+auth.init_db()
+
+
+# ── Protected routes ──────────────────────────────────────────────────────────
+
+@app.route("/profile")
+@auth.login_required
+def profile():
+    return jsonify(g.user.to_dict())
+
+
+@app.route("/admin")
+@auth.admin_required
+def admin_dashboard():
+    return jsonify({"message": f"Welcome, admin {g.user.email}"})
+
+
+@app.route("/manager")
+@auth.require_role("manager")
+def manager_page():
+    return jsonify({"message": f"Welcome, manager {g.user.email}"})
+
+
+if __name__ == "__main__":
+    app.run(debug=True)
+''',
+        encoding="utf-8",
+    )
+    typer.echo("Created app.py — run with:  flask run")
+
+
+# ── softauth setup django ─────────────────────────────────────────────────────
+
+@setup_app.command("django")
+def setup_django() -> None:
+    """Generate a ready-to-run Django application with softauth wired in."""
+    target = Path("views.py")
+    if target.exists():
+        typer.echo("views.py already exists — skipping.")
+        raise typer.Exit()
+
+    target.write_text(
+        '''\
+from django.http import JsonResponse
+from softauth import SoftAuth
+from dotenv import load_dotenv
+import os
+
+load_dotenv()
+
+auth = SoftAuth(
+    secret_key=os.environ["SOFTAUTH_SECRET"],
+    framework="django",
+    database_url=os.getenv("SOFTAUTH_DB_URL", "sqlite:///auth.db"),
+)
+auth.init_db()
+
+
+# ── In urls.py ────────────────────────────────────────────────────────────────
+#
+# from django.urls import path
+# from .views import auth
+#
+# urlpatterns = []
+# auth.init_app(urlpatterns)   # appends /auth/* routes
+#
+# Also add to settings.py MIDDLEWARE:
+#   "softauth.django.middleware.SoftAuthMiddleware",
+
+
+# ── Protected views ───────────────────────────────────────────────────────────
+
+@auth.login_required
+def profile(request):
+    return JsonResponse(request.softauth_user.to_dict())
+
+
+@auth.admin_required
+def admin_dashboard(request):
+    return JsonResponse({"message": f"Welcome, admin {request.softauth_user.email}"})
+
+
+@auth.require_role("manager")
+def manager_page(request):
+    return JsonResponse({"message": f"Welcome, manager {request.softauth_user.email}"})
+''',
+        encoding="utf-8",
+    )
+    typer.echo("Created views.py — wire it into urls.py and add SoftAuthMiddleware to MIDDLEWARE.")
+
+
+# ── softauth secret ────────────────────────────────────────────────────────────
+
+@app.command()
+def secret(
+    length: int = typer.Option(32, "--length", "-l", help="Number of random bytes (hex output is 2× longer)"),
+) -> None:
+    """Print a cryptographically secure random secret key."""
+    typer.echo(secrets.token_hex(length))

softauth/core/__init__.py

@@ -0,0 +1,35 @@
+from softauth.core.auth import SoftAuth
+from softauth.core.config import SoftAuthConfig
+from softauth.core.exceptions import (
+    AdapterNotInitializedError,
+    AuthError,
+    ConfigurationError,
+    InactiveUserError,
+    InvalidCredentialsError,
+    InvalidTokenError,
+    PermissionDeniedError,
+    SoftAuthError,
+    TokenError,
+    TokenExpiredError,
+    TokenTypeMismatchError,
+    UserAlreadyExistsError,
+    UserNotFoundError,
+)
+
+__all__ = [
+    "SoftAuth",
+    "SoftAuthConfig",
+    "SoftAuthError",
+    "AuthError",
+    "TokenError",
+    "TokenExpiredError",
+    "InvalidTokenError",
+    "TokenTypeMismatchError",
+    "InvalidCredentialsError",
+    "InactiveUserError",
+    "UserNotFoundError",
+    "UserAlreadyExistsError",
+    "PermissionDeniedError",
+    "ConfigurationError",
+    "AdapterNotInitializedError",
+]

softauth/core/auth.py

@@ -0,0 +1,183 @@
+"""SoftAuth — the public facade for the entire library.
+
+Usage (FastAPI):
+    auth = SoftAuth(secret_key="...", framework="fastapi")
+    auth.init_app(app)
+    auth.init_db()
+
+Usage (Flask):
+    auth = SoftAuth(secret_key="...", framework="flask")
+    auth.init_app(app)
+    auth.init_db()
+
+The core is framework-agnostic: JWT and password handling live in
+``softauth.jwt`` and ``softauth.security``.  Framework adapters (FastAPI,
+Flask, …) implement ``BaseAdapter`` and are loaded lazily so that having
+only one framework installed does not cause import errors.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Callable, Optional
+
+from softauth.core.config import SoftAuthConfig
+from softauth.core.exceptions import AdapterNotInitializedError, ConfigurationError
+from softauth.database.session import DatabaseSession
+from softauth.interfaces.adapter import BaseAdapter
+from softauth.jwt.handler import JWTHandler
+from softauth.security.password import PasswordHandler
+
+
+class SoftAuth:
+    """Zero-setup JWT authentication for FastAPI and Flask.
+
+    All arguments to ``__init__`` mirror ``SoftAuthConfig`` fields.
+    Pass any SoftAuthConfig field as a keyword argument.
+    """
+
+    def __init__(
+        self,
+        secret_key: str,
+        *,
+        framework: Optional[str] = None,
+        database_url: str = "sqlite:///auth.db",
+        algorithm: str = "HS256",
+        access_expiry_minutes: int = 15,
+        refresh_expiry_days: int = 7,
+        auth_prefix: str = "/auth",
+        enable_refresh_tokens: bool = True,
+    ) -> None:
+        self.config = SoftAuthConfig(
+            secret_key=secret_key,
+            framework=framework,  # type: ignore[arg-type]
+            database_url=database_url,
+            algorithm=algorithm,
+            access_expiry_minutes=access_expiry_minutes,
+            refresh_expiry_days=refresh_expiry_days,
+            auth_prefix=auth_prefix,
+            enable_refresh_tokens=enable_refresh_tokens,
+        )
+        self.jwt = JWTHandler(self.config)
+        self.passwords = PasswordHandler()
+        self._db = DatabaseSession(self.config.database_url)
+        self._adapter: Optional[BaseAdapter] = None
+
+    # ── Initialisation ────────────────────────────────────────────────────
+
+    def init_app(self, app: Any) -> None:
+        """Attach SoftAuth to *app*.
+
+        Mounts routes and middleware for the configured framework.
+        Must be called before the first request is served.
+        """
+        fw = self.config.framework
+        if fw == "fastapi":
+            from softauth.fastapi.adapter import FastAPIAdapter
+            self._adapter = FastAPIAdapter(self, self.config)
+        elif fw == "flask":
+            from softauth.flask.adapter import FlaskAdapter
+            self._adapter = FlaskAdapter(self, self.config)
+        elif fw == "django":
+            from softauth.django.adapter import DjangoAdapter
+            self._adapter = DjangoAdapter(self, self.config)
+        elif fw is None:
+            raise ConfigurationError(
+                "No framework specified.  Pass framework='fastapi' or framework='flask' "
+                "to SoftAuth(), or use a custom adapter."
+            )
+        else:
+            raise ConfigurationError(
+                f"Unknown framework '{fw}'.  "
+                "Built-in choices: 'fastapi', 'flask', 'django'.  "
+                "For other frameworks implement BaseAdapter and call use_adapter()."
+            )
+
+        self._adapter.on_startup()
+        self._adapter.init_app(app)
+
+    def use_adapter(self, adapter: BaseAdapter, app: Any) -> None:
+        """Register a custom BaseAdapter instead of a built-in one.
+
+        This is the extension point for Django, Litestar, Quart, or any
+        other framework without touching SoftAuth internals.
+
+        Example::
+
+            class DjangoAdapter(BaseAdapter): ...
+
+            auth = SoftAuth(secret_key="...", framework=None)
+            auth.use_adapter(DjangoAdapter(auth, auth.config), django_app)
+        """
+        self._adapter = adapter
+        adapter.on_startup()
+        adapter.init_app(app)
+
+    def init_db(self) -> None:
+        """Create the softauth_users table (and any future tables).
+
+        Idempotent — safe to call on every startup.
+        """
+        self._db.create_tables()
+
+    # ── Auth dependency / decorator accessors ─────────────────────────────
+
+    def _require_adapter(self) -> BaseAdapter:
+        if self._adapter is None:
+            raise AdapterNotInitializedError(
+                "Call auth.init_app(app) before accessing auth dependencies."
+            )
+        return self._adapter
+
+    @property
+    def current_user(self) -> Any:
+        """FastAPI: ``Depends(auth.current_user)``  |  Flask: ``@auth.login_required``."""
+        return self._require_adapter().get_current_user_dependency()
+
+    @property
+    def current_admin(self) -> Any:
+        """FastAPI: ``Depends(auth.current_admin)``  |  Flask: ``@auth.admin_required``."""
+        return self._require_adapter().get_current_admin_dependency()
+
+    def require_role(self, role: str) -> Any:
+        """FastAPI: ``Depends(auth.require_role('editor'))``
+           Flask:   ``@auth.require_role('editor')``
+        """
+        return self._require_adapter().get_require_role_dependency(role)
+
+    # ── Flask-flavoured shorthand properties ──────────────────────────────
+
+    @property
+    def login_required(self) -> Any:
+        """Flask convenience alias for ``current_user`` (used as decorator)."""
+        adapter = self._require_adapter()
+        if not hasattr(adapter, "login_required"):
+            return adapter.get_current_user_dependency()
+        return adapter.login_required  # type: ignore[union-attr]
+
+    @property
+    def admin_required(self) -> Any:
+        """Flask convenience alias for ``current_admin`` (used as decorator)."""
+        adapter = self._require_adapter()
+        if not hasattr(adapter, "admin_required"):
+            return adapter.get_current_admin_dependency()
+        return adapter.admin_required  # type: ignore[union-attr]
+
+    # ── Convenience passthrough ────────────────────────────────────────────
+
+    def hash_password(self, plain: str) -> str:
+        return self.passwords.hash_password(plain)
+
+    def verify_password(self, plain: str, hashed: str) -> bool:
+        return self.passwords.verify_password(plain, hashed)
+
+    def create_access_token(self, subject: str, role: Optional[str] = None, **extra: Any) -> str:
+        return self.jwt.create_access_token(subject, role=role, extra=extra or None)
+
+    def create_refresh_token(self, subject: str) -> str:
+        return self.jwt.create_refresh_token(subject)
+
+    def decode_token(self, token: str) -> dict[str, Any]:
+        return self.jwt.decode_token(token)
+
+    def verify_token(self, token: str) -> bool:
+        return self.jwt.verify_token(token)

softauth/core/config.py

@@ -0,0 +1,70 @@
+"""Runtime configuration for SoftAuth.
+
+All fields can be overridden by keyword arguments to ``SoftAuth()``.
+Environment variables are picked up automatically when ``from_env()`` is used.
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Literal, Optional
+
+from pydantic import BaseModel, Field, field_validator
+
+
+class SoftAuthConfig(BaseModel):
+    """Immutable configuration object passed through the entire library.
+
+    Prefer constructing via ``SoftAuth(...)`` rather than directly.
+    """
+
+    model_config = {"frozen": True}
+
+    # ── Core security ──────────────────────────────────────────────────────
+    secret_key: str = Field(..., min_length=16)
+    algorithm: str = Field("HS256")
+
+    # ── Token lifetimes ────────────────────────────────────────────────────
+    access_expiry_minutes: int = Field(15, gt=0)
+    refresh_expiry_days: int = Field(7, gt=0)
+
+    # ── Framework adapter ──────────────────────────────────────────────────
+    # None means "framework-agnostic / manual" — useful for testing or custom
+    # adapters.  Built-in values: "fastapi", "flask".  Unknown strings are
+    # accepted here so that use_adapter() + framework=None works, and so that
+    # typos produce a ConfigurationError in init_app() rather than a Pydantic
+    # ValidationError at construction time.
+    framework: Optional[str] = None
+
+    # ── Database ───────────────────────────────────────────────────────────
+    database_url: str = Field("sqlite:///auth.db")
+
+    # ── Routing ────────────────────────────────────────────────────────────
+    auth_prefix: str = Field("/auth")
+    token_prefix: str = Field("Bearer")
+
+    # ── Behaviour flags ────────────────────────────────────────────────────
+    enable_refresh_tokens: bool = True
+
+    @field_validator("secret_key")
+    @classmethod
+    def _secret_not_placeholder(cls, v: str) -> str:
+        if v.lower() in {"secret", "changeme", "change-me", "your-secret-key"}:
+            import warnings
+            warnings.warn(
+                "SoftAuth secret_key looks like a placeholder. "
+                "Use a strong random value in production.",
+                stacklevel=2,
+            )
+        return v
+
+    @classmethod
+    def from_env(cls, **overrides: object) -> "SoftAuthConfig":
+        """Build config from environment variables, with keyword overrides."""
+        env: dict[str, object] = {
+            "secret_key": os.environ.get("SOFTAUTH_SECRET", ""),
+            "database_url": os.environ.get("SOFTAUTH_DB_URL", "sqlite:///auth.db"),
+            "algorithm": os.environ.get("SOFTAUTH_ALGORITHM", "HS256"),
+        }
+        env.update(overrides)
+        return cls(**env)  # type: ignore[arg-type]

softauth/core/exceptions.py

@@ -0,0 +1,67 @@
+"""Hierarchy of SoftAuth exceptions.
+
+Every exception the library raises is a subclass of SoftAuthError so callers
+can catch the whole tree with a single ``except SoftAuthError`` if they need to.
+"""
+
+
+class SoftAuthError(Exception):
+    """Root exception for all softauth errors."""
+
+
+# ── Authentication ────────────────────────────────────────────────────────────
+
+class AuthError(SoftAuthError):
+    """Raised for general authentication failures."""
+
+
+class InvalidCredentialsError(AuthError):
+    """Wrong email / password combination."""
+
+
+class InactiveUserError(AuthError):
+    """Account exists but has been deactivated."""
+
+
+# ── Token ─────────────────────────────────────────────────────────────────────
+
+class TokenError(SoftAuthError):
+    """Base class for all token-related errors."""
+
+
+class TokenExpiredError(TokenError):
+    """JWT has passed its expiry timestamp."""
+
+
+class InvalidTokenError(TokenError):
+    """JWT signature is bad, format is wrong, or claims are missing."""
+
+
+class TokenTypeMismatchError(TokenError):
+    """e.g. a refresh token was presented where an access token is expected."""
+
+
+# ── User / identity ───────────────────────────────────────────────────────────
+
+class UserNotFoundError(SoftAuthError):
+    """No user record matches the given identifier."""
+
+
+class UserAlreadyExistsError(SoftAuthError):
+    """A user with this email already exists."""
+
+
+# ── Authorisation ─────────────────────────────────────────────────────────────
+
+class PermissionDeniedError(SoftAuthError):
+    """Authenticated user lacks the required role."""
+
+
+# ── Configuration ─────────────────────────────────────────────────────────────
+
+class ConfigurationError(SoftAuthError):
+    """Invalid or missing SoftAuth configuration."""
+
+
+class AdapterNotInitializedError(SoftAuthError):
+    """init_app() has not been called yet."""

softauth/database/__init__.py

@@ -0,0 +1,5 @@
+from softauth.database.models import Base, User
+from softauth.database.repository import UserRepository
+from softauth.database.session import DatabaseSession
+
+__all__ = ["Base", "User", "UserRepository", "DatabaseSession"]