py-auth-core 0.0.1__py3-none-any.whl

py_auth/__init__.py

@@ -0,0 +1,45 @@
+"""
+py-auth: Modular authentication primitives and provider framework for Python backends.
+"""
+
+from .base import BaseProvider
+from .core import PyAuth
+from .exceptions import (
+    AdapterError,
+    ConfigurationError,
+    DuplicateEntryError,
+    ForeignKeyViolationError,
+    PyAuthError,
+    RecordNotFoundError,
+)
+from .providers.credentials import CredentialsProvider
+from .schemas import (
+    AdapterContainer,
+    AuthError,
+    AuthResult,
+    CookieConfig,
+    CookieOptions,
+    PyAuthAdapterProtocol,
+    PyAuthCookiesInput,
+)
+
+__all__ = [
+    "PyAuth",
+    "BaseProvider",
+    "CredentialsProvider",
+    "PyAuthError",
+    "DuplicateEntryError",
+    "ForeignKeyViolationError",
+    "RecordNotFoundError",
+    "AdapterError",
+    "ConfigurationError",
+    "AuthError",
+    "AuthResult",
+    "CookieOptions",
+    "CookieConfig",
+    "PyAuthCookiesInput",
+    "PyAuthAdapterProtocol",
+    "AdapterContainer",
+]
+
+__version__ = "0.0.1"

py_auth/base.py

@@ -0,0 +1,20 @@
+from abc import ABC, abstractmethod
+from typing import Any
+
+from .schemas import AuthResult
+
+
+class BaseProvider(ABC):
+    """Abstract base class for all authentication providers."""
+
+    id: str
+
+    def __init__(self) -> None:
+        self.id = self.__class__.__name__.lower().replace("provider", "")
+
+    @abstractmethod
+    async def handle_request(self, *args: Any, **kwargs: Any) -> AuthResult:
+        pass
+
+
+__all__ = ["BaseProvider"]

py_auth/core.py

@@ -0,0 +1,259 @@
+import hmac
+
+from datetime import datetime, timedelta, timezone
+from typing import Any, Dict, List, Optional
+
+from .exceptions import (
+    DuplicateEntryError,
+    ForeignKeyViolationError,
+    RecordNotFoundError,
+)
+from .utils import generate_token, hash_token, merge_cookie_config, get_logger
+from .schemas import (
+    AdapterContainer,
+    AuthError,
+    AuthResult,
+    PyAuthCookiesInput,
+)
+
+class PyAuth:
+    """Core py-auth authentication manager."""
+
+    def __init__(
+        self,
+        adapter: Any,
+        providers: Optional[List[Any]] = None,
+        cookies: Optional[PyAuthCookiesInput] = None,
+    ):
+        container = AdapterContainer(adapter=adapter)
+        self.adapter = container.adapter
+        self.cookies = merge_cookie_config(user_config=cookies)
+        self._provider_map = {getattr(p, "id", None): p for p in (providers or [])}
+
+    def get_auth_result(
+        self,
+        data: Optional[Any] = None,
+        error: Optional[AuthError] = None,
+    ) -> AuthResult:
+        """Construct a standardized py-auth response."""
+        return {"data": data, "error": error}
+
+    def get_signin_with_credentials_result(
+        self,
+        session_token: str,
+        csrf_token: str,
+        user: Dict[str, Any],
+    ) -> AuthResult:
+        """Construct a standardized credentials sign-in success response."""
+        return {
+            "data": {
+                "session_token": session_token,
+                "csrf_token": csrf_token,
+                "user": user,
+            },
+            "error": None,
+        }
+
+    async def verify_session(self, session_token: str, csrf_token: str) -> AuthResult:
+        """Verify an active session and ensure CSRF token validity."""
+        if not session_token:
+            return self.get_auth_result(
+                error={
+                    "code": "MissingSessionToken",
+                    "status_code": 401,
+                    "message": "Session token was not provided.",
+                }
+            )
+
+        if not csrf_token:
+            return self.get_auth_result(
+                error={
+                    "code": "MissingCsrfToken",
+                    "status_code": 401,
+                    "message": "CSRF token was not provided.",
+                }
+            )
+
+        session_token_hash = hash_token(session_token)
+        session = await self.adapter.get_session_by_session_token_hash(
+            session_token_hash
+        )
+
+        if not session:
+            return self.get_auth_result(
+                error={
+                    "code": "InvalidSessionToken",
+                    "status_code": 401,
+                    "message": "Session token not found or invalid.",
+                }
+            )
+
+        expires = session.get("expires")
+        now = datetime.now(timezone.utc)
+        if not isinstance(expires, datetime):
+            return self.get_auth_result(
+                error={
+                    "code": "InvalidSessionData",
+                    "status_code": 401,
+                    "message": "Session expiration format is invalid.",
+                }
+            )
+
+        if expires.tzinfo is None:
+            expires = expires.replace(tzinfo=timezone.utc)
+
+        if expires <= now:
+            await self.adapter.delete_session_by_session_token_hash(session_token_hash)
+            return self.get_auth_result(
+                error={
+                    "code": "SessionExpired",
+                    "status_code": 401,
+                    "message": "Session has expired. Sign in again to continue.",
+                },
+            )
+
+        db_csrf_token = session.get("csrf_token")
+        if not db_csrf_token or not hmac.compare_digest(db_csrf_token, csrf_token):
+            return self.get_auth_result(
+                error={
+                    "code": "InvalidCsrfToken",
+                    "status_code": 403,
+                    "message": "CSRF token validation failed.",
+                }
+            )
+
+        return self.get_auth_result(data={"session": session})
+
+    async def signout(self, session_id: str) -> AuthResult:
+        """Invalidate and delete the session identified by session_id with error handling."""
+        try:
+            await self.adapter.delete_session(session_id)
+            return self.get_auth_result(data={"signed_out": True})
+        except RecordNotFoundError:
+            return self.get_auth_result(data={"signed_out": True})
+        except Exception as e:
+            get_logger().exception("Unexpected error during signout:", e)
+            return self.get_auth_result(
+                error={
+                    "code": "InternalServerError",
+                    "status_code": 500,
+                    "message": "An internal error occurred.",
+                }
+            )
+
+    async def update_session_csrf_token(self, session_id: str) -> AuthResult:
+        """Updates the CSRF token for a given session with error handling."""
+        new_csrf_token = generate_token(num_bytes=32)
+        try:
+            updated = await self.adapter.update_session(
+                session_id, {"csrf_token": new_csrf_token}
+            )
+            if not updated:
+                return self.get_auth_result(
+                    error={
+                        "code": "RecordNotFound",
+                        "status_code": 404,
+                        "message": "Session not found for CSRF rotation.",
+                    }
+                )
+            return self.get_auth_result(data={"csrf_token": new_csrf_token})
+
+        except RecordNotFoundError:
+            return self.get_auth_result(
+                error={
+                    "code": "RecordNotFound",
+                    "status_code": 404,
+                    "message": "Session not found.",
+                }
+            )
+        except Exception as e:
+            get_logger().exception("Unexpected error during CSRF token update:", e)
+            return self.get_auth_result(
+                error={
+                    "code": "InternalServerError",
+                    "status_code": 500,
+                    "message": "An internal error occurred.",
+                }
+            )
+
+    async def signin_with_credentials(self, request_body: Dict[str, Any]) -> AuthResult:
+        """Authenticate user credentials, create a session, and return session tokens."""
+        credentials_provider = self._provider_map.get("credentials")
+
+        if not credentials_provider:
+            return self.get_auth_result(
+                error={
+                    "code": "ConfigurationError",
+                    "status_code": 500,
+                    "message": "Credentials provider is not configured.",
+                }
+            )
+
+        result = await credentials_provider.handle_request(request_body)
+        error = result["error"]
+        user_data = result["data"]
+
+        if error:
+            return self.get_auth_result(error=error)
+
+        expires = (datetime.now(timezone.utc) + timedelta(days=30)).replace(tzinfo=None)
+        session_token = generate_token(num_bytes=48)
+        csrf_token = generate_token(num_bytes=32)
+
+        max_retries = 3
+        created_session = None
+        for _ in range(max_retries):
+            session_token_hash = hash_token(session_token)
+            try:
+                created_session = await self.adapter.create_session(
+                    {
+                        "session_token_hash": session_token_hash,
+                        "user_id": user_data.get("id", None),
+                        "csrf_token": csrf_token,
+                        "expires": expires,
+                    }
+                )
+                break
+
+            except DuplicateEntryError:
+                session_token = generate_token(num_bytes=48)
+
+            except ForeignKeyViolationError as e:
+                get_logger().exception(
+                    "Foreign key violation occurred while creating session: referenced user record not found.",
+                    e,
+                )
+                status_code = getattr(e, "status_code", 400)
+                return self.get_auth_result(
+                    error={
+                        "code": "ForeignKeyViolation",
+                        "status_code": status_code,
+                        "message": "The user account associated with this login no longer exists.",
+                    }
+                )
+
+            except Exception as e:
+                get_logger().exception(
+                    "Unexpected error occurred during session creation:", e
+                )
+                status_code = getattr(e, "status_code", 500)
+                return self.get_auth_result(
+                    error={
+                        "code": "InternalServerError",
+                        "status_code": status_code,
+                        "message": "An internal error occurred.",
+                    }
+                )
+
+        if not created_session:
+            return self.get_auth_result(
+                error={
+                    "code": "SessionCreationFailed",
+                    "status_code": 500,
+                    "message": "Failed to create session after multiple attempts. Please try again.",
+                }
+            )
+
+        return self.get_signin_with_credentials_result(
+            session_token=session_token, csrf_token=csrf_token, user=user_data
+        )

py_auth/exceptions.py

@@ -0,0 +1,54 @@
+"""
+Core exception classes for py-auth.
+"""
+
+
+class PyAuthError(Exception):
+    """Base exception for all py-auth errors."""
+
+    status_code: int = 500
+
+    def __init__(self, message: str = "", status_code: int | None = None) -> None:
+        super().__init__(message)
+        if status_code is not None:
+            self.status_code = status_code
+
+
+class DuplicateEntryError(PyAuthError):
+    """Raised when a unique constraint or duplicate entry violation occurs (HTTP 409)."""
+
+    status_code: int = 409
+
+
+class ForeignKeyViolationError(PyAuthError):
+    """Raised when a foreign key constraint violation occurs (HTTP 400)."""
+
+    status_code: int = 400
+
+
+class RecordNotFoundError(PyAuthError):
+    """Raised when a requested database record cannot be found (HTTP 404)."""
+
+    status_code: int = 404
+
+
+class AdapterError(PyAuthError):
+    """Raised when an adapter or database engine is misconfigured or fails setup (HTTP 500)."""
+
+    status_code: int = 500
+
+
+class ConfigurationError(PyAuthError):
+    """Raised when the core library is misconfigured during setup (HTTP 500)."""
+
+    status_code: int = 500
+
+
+__all__ = [
+    "PyAuthError",
+    "DuplicateEntryError",
+    "ForeignKeyViolationError",
+    "RecordNotFoundError",
+    "AdapterError",
+    "ConfigurationError",
+]

py_auth/providers/__init__.py

@@ -0,0 +1,7 @@
+"""
+Authentication providers for py-auth.
+"""
+
+from .credentials import (CredentialsProvider,ValidationError)
+
+__all__ = ["CredentialsProvider","ValidationError",]

py_auth/providers/credentials.py

@@ -0,0 +1,80 @@
+import inspect
+
+from pydantic import BaseModel, ValidationError as PydanticValidationError
+from typing import Any, Awaitable, Callable, Dict, List, Optional, TypedDict, Union, Type
+
+from ..base import BaseProvider
+from ..schemas import AuthResult
+from ..utils import get_logger
+
+
+class ValidationError(TypedDict):
+    """Represents structured field validation errors for request bodies."""
+
+    field: str
+    errors: List[str]
+
+class CredentialsProvider(BaseProvider):
+    """Provider for credential-based authentication.
+
+    Handles credential validation, sanitization, and user-defined authorization callbacks.
+    """
+
+    def __init__(
+        self,
+        model: Type[BaseModel],
+        authorize: Union[Callable[[Dict[str, Any]], Any], Callable[[Dict[str, Any]], Awaitable[Any]]],
+    ) -> None:
+        super().__init__()
+        self.model = model
+        self.authorize = authorize
+
+    async def handle_request(self, request_body: Dict[str, Any]) -> AuthResult:
+        """Validate request data using the Pydantic model and execute the authorization callback."""
+        try:
+            validated_data = self.model.model_validate(request_body)
+            payload = validated_data.model_dump()
+        except PydanticValidationError as e:
+            formatted_errors: list[ValidationError] = [
+                {"field": ".".join(str(loc) for loc in err["loc"]), "errors": [err["msg"]]}
+                for err in e.errors()
+            ]
+
+            return {
+                "data": None,
+                "error": {
+                    "code": "ValidationError",
+                    "status_code": 422,
+                    "message": "Validation failed.",
+                    "details":{"validation_errors": formatted_errors}
+                },
+            }
+
+        try:
+            if inspect.iscoroutinefunction(self.authorize):
+                result = await self.authorize(payload)
+            else:
+                result = self.authorize(payload)
+
+            if not result:
+                return {
+                    "data": None,
+                    "error": {
+                      "code": "CredentialsSignIn",
+                      "status_code": 401, 
+                      "message": "Invalid email or password."
+                    },
+                }
+            return {"data": result, "error": None}
+        except Exception as e:
+            get_logger().exception("Unhandled exception during credentials authorization callback: %s", e)
+            return {
+                "data": None,
+                "error": {
+                    "code": "ServerError",
+                    "status_code": 500,
+                    "message": "An internal server error occurred.",
+                },
+            }
+
+__all__ = ["ValidationError","CredentialsProvider"]

py_auth/py.typed

@@ -0,0 +1 @@
+# Marker file for PEP 561.

py_auth/schemas.py

@@ -0,0 +1,90 @@
+import datetime
+
+from typing import (
+    Any,
+    Dict,
+    Literal,
+    Optional,
+    Protocol,
+    TypedDict,
+    runtime_checkable,
+)
+from pydantic import BaseModel, ConfigDict, field_validator
+from .exceptions import ConfigurationError
+
+
+class AuthError(TypedDict, total=False):
+    code: str
+    status_code: int
+    message: str
+    details: Optional[Dict[str, Any]]
+
+
+class AuthResult(TypedDict):
+    data: Optional[Any]
+    error: Optional[AuthError]
+
+
+class CookieOptions(BaseModel):
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
+    http_only: Optional[bool] = None
+    secure: Optional[bool] = None
+    same_site: Optional[Literal["lax", "strict", "none"]] = None
+    path: Optional[str] = None
+    domain: Optional[str] = None
+    max_age: Optional[int] = None
+    expires: Optional[datetime.datetime] = None
+
+
+class CookieConfig(BaseModel):
+    name: Optional[str] = None
+    options: Optional[CookieOptions] = None
+
+
+class PyAuthCookiesInput(BaseModel):
+    session_token: Optional[CookieConfig] = None
+    csrf_token: Optional[CookieConfig] = None
+
+
+@runtime_checkable
+class PyAuthAdapterProtocol(Protocol):
+    """Defines the strict structural contract that any py-auth adapter must implement."""
+
+    async def create_session(self, session_data: Dict[str, Any]) -> Dict[str, Any]: ...
+    async def get_session_by_session_token_hash(
+        self, session_token_hash: str
+    ) -> Optional[Dict[str, Any]]: ...
+    async def delete_session_by_session_token_hash(
+        self, session_token_hash: str
+    ) -> None: ...
+    async def delete_session(self, session_id: str) -> None: ...
+    async def update_session(
+        self, session_id: str, updates: Dict
+    ) -> Optional[Dict]: ...
+
+
+class AdapterContainer(BaseModel):
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+    adapter: Any
+
+    @field_validator("adapter", mode="before")
+    @classmethod
+    def validate_adapter_interface(cls, v: Any) -> Any:
+        if not isinstance(v, PyAuthAdapterProtocol):
+            raise ConfigurationError(
+                "The provided adapter is missing required methods or attributes defined in 'PyAuthAdapterProtocol'."
+            )
+
+        return v
+
+
+__all__ = [
+    "AuthError",
+    "AuthResult",
+    "CookieOptions",
+    "CookieConfig",
+    "PyAuthCookiesInput",
+    "PyAuthAdapterProtocol",
+    "AdapterContainer",
+]

py_auth/utils.py

@@ -0,0 +1,105 @@
+import os, hashlib, secrets, logging
+
+from typing import Any, Dict, Mapping, Optional, Union
+
+from .schemas import CookieConfig, PyAuthCookiesInput
+
+
+def generate_token(num_bytes: int = 32) -> str:
+    """Generate a cryptographically secure URL-safe token."""
+    return secrets.token_urlsafe(num_bytes)
+
+
+def hash_token(token: str) -> str:
+    """Produce a SHA-256 hash digest of a given token string."""
+    return hashlib.sha256(token.encode("utf-8")).hexdigest()
+
+
+def get_logger():
+    """Retrieve the centralized namespaced logger for the py-auth library.
+
+    Using a dedicated namespace ('py_auth') allows consuming applications
+    to configure logging levels, formats, or handlers specifically for this
+    package without polluting or altering the main application's logs.
+    """
+    return logging.getLogger("py_auth")
+
+
+_DEFAULTS = {
+    "session_token": {
+        "name": "__Host-py_auth_session",
+        "options": {
+            "http_only": True,
+            "secure": True,
+            "same_site": "lax",
+            "path": "/",
+            "max_age": 30 * 24 * 60 * 60,
+        },
+    },
+    "csrf_token": {
+        "name": "py_auth_csrf",
+        "options": {
+            "http_only": False,
+            "secure": True,
+            "same_site": "lax",
+            "path": "/",
+            "max_age": 60 * 60,
+        },
+    },
+}
+
+
+def merge_cookie_config(
+    user_config: Optional[Union[PyAuthCookiesInput, Dict[str, Any]]] = None,
+    *,
+    is_production: bool = os.environ.get("ENVIRONMENT", "development") == "production",
+) -> Dict[str, Dict[str, Any]]:
+    """Merge user cookie options with safe defaults based on environment."""
+
+    if isinstance(user_config, PyAuthCookiesInput):
+        user_config_dict = user_config.model_dump(exclude_unset=True)
+    elif isinstance(user_config, dict):
+        user_config_dict = user_config
+    else:
+        user_config_dict = {}
+
+    # Avoid slow copy.deepcopy by constructing a shallow/dict copy inline
+    defaults = {
+        k: {"name": v["name"], "options": v["options"].copy()}
+        for k, v in _DEFAULTS.items()
+    }
+
+    keys = defaults.keys() | user_config_dict.keys()
+    result: Dict[str, Dict[str, Any]] = {}
+
+    for key in keys:
+        default_cfg = defaults.get(key)
+        if default_cfg:
+            merged_name = default_cfg["name"]
+            merged_opts = default_cfg["options"].copy()
+        else:
+            merged_name = key
+            merged_opts = {"path": "/", "secure": is_production}
+
+        user_val = user_config_dict.get(key)
+
+        if isinstance(user_val, str):
+            merged_name = user_val
+        elif user_val is not None:
+            if isinstance(user_val, CookieConfig):
+                parsed = user_val
+            elif isinstance(user_val, Mapping):
+                parsed = CookieConfig.model_validate(user_val)
+            else:
+                parsed = None
+
+            if parsed:
+                if parsed.name is not None:
+                    merged_name = parsed.name
+                if parsed.options is not None:
+                    merged_opts.update(parsed.options.model_dump(exclude_none=True))
+
+        merged_opts.setdefault("secure", is_production)
+        result[key] = {"name": merged_name, "options": merged_opts}
+
+    return result

py_auth_core-0.0.1.dist-info/METADATA

@@ -0,0 +1,463 @@
+Metadata-Version: 2.4
+Name: py-auth-core
+Version: 0.0.1
+Summary: Core auth primitives and provider framework for py-auth-core.
+Author-email: Olatunji Jamaldeen Omotoyosi <jamaldeen.o@yahoo.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/jamaldeen09/py-auth
+Project-URL: Repository, https://github.com/jamaldeen09/py-auth
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pydantic<3.0.0,>=2.0.0
+Provides-Extra: postgres
+Requires-Dist: asyncpg>=0.28.0; extra == "postgres"
+Provides-Extra: mysql
+Requires-Dist: aiomysql>=0.2.0; extra == "mysql"
+Provides-Extra: sqlite
+Requires-Dist: aiosqlite>=0.19.0; extra == "sqlite"
+Dynamic: license-file
+
+# py-auth-core
+
+**Modular, framework-agnostic authentication primitives for Python backends.**
+
+`py-auth-core` gives you secure session management, credential-based sign-in, CSRF protection, and a clean provider/adapter architecture — without forcing a specific ORM, web framework, or database on you.
+
+[![PyPI version](https://img.shields.io/pypi/v/py-auth-core.svg)](https://pypi.org/project/py-auth-core/)
+[![Python versions](https://img.shields.io/pypi/pyversions/py-auth-core.svg)](https://pypi.org/project/py-auth-core/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+---
+
+## Table of Contents
+
+- [Features](#features)
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Core Concepts](#core-concepts)
+  - [PyAuth](#pyauth-1)
+  - [Providers](#providers)
+  - [Adapters](#adapters)
+  - [Cookies](#cookies)
+- [API Reference](#api-reference)
+  - [PyAuth class](#pyauth-class)
+  - [CredentialsProvider](#credentialsprovider)
+  - [BaseProvider](#baseprovider)
+  - [Schemas & TypedDicts](#schemas--typeddicts)
+  - [Exceptions](#exceptions)
+- [Integrations](#integrations)
+- [Available Adapters](#available-adapters)
+- [Roadmap](#roadmap)
+- [Security Notes](#security-notes)
+- [Contributing](#contributing)
+- [License](#license)
+
+---
+
+## Features
+
+- ✅ **Async-first** — every auth operation is a coroutine
+- ✅ **Provider pattern** — plug in `CredentialsProvider` or use an upcoming provider
+- ✅ **Adapter pattern** — swap the database layer without touching auth logic
+- ✅ **Secure by default** — SHA-256 session-token hashing, `httpOnly` + `Secure` cookies, CSRF protection via `hmac.compare_digest`
+- ✅ **Pydantic v2** request validation built-in
+- ✅ **Framework-agnostic** — works with FastAPI, Starlette, Django, Flask, or any async Python backend
+- ✅ **Typed throughout** — ships a `py.typed` marker; full TypedDict / Protocol coverage
+
+---
+
+## Installation
+
+```bash
+pip install py-auth-core
+```
+
+`py-auth-core` requires **Python ≥ 3.9** and **Pydantic ≥ 2.0**.
+
+---
+
+## Quick Start
+
+Below is a minimal example using `py-auth-core` directly. If you're on **FastAPI**, see [Integrations](#integrations) — the official integration reduces this to a single line.
+
+```python
+from pydantic import BaseModel, EmailStr
+from py_auth import PyAuth, CredentialsProvider
+
+
+# 1. Define your credentials schema (Pydantic v2)
+class LoginSchema(BaseModel):
+    email: EmailStr
+    password: str
+
+
+# 2. Implement your authorization callback
+async def authorize(credentials: dict) -> dict | None:
+    """Check if the user exists — create them if not. Return None to reject."""
+    user = await db.find_user_by_email(credentials["email"])
+
+    if user:
+        # Existing user — verify their password
+        if not verify_password(credentials["password"], user.hashed_password):
+            return None
+        return {"id": str(user.id), "email": user.email, "name": user.name}
+
+    # New user — create them and return their details
+    new_user = await db.create_user(
+        email=credentials["email"],
+        hashed_password=hash_password(credentials["password"]),
+    )
+    return {"id": str(new_user.id), "email": new_user.email, "name": new_user.name}
+
+
+# 3. Wire everything together
+credentials_provider = CredentialsProvider(model=LoginSchema, authorize=authorize)
+
+auth = PyAuth(
+    adapter=my_adapter,  # any PyAuthAdapterProtocol-compliant adapter
+    providers=[credentials_provider],
+)
+```
+
+Once `auth` is set up, use it in your route handlers:
+
+```python
+# Sign in
+result = await auth.signin_with_credentials(request_body)
+
+# Verify an active session
+result = await auth.verify_session(session_token, csrf_token)
+
+# Sign out
+result = await auth.signout(session_id)
+```
+
+Every method returns an `AuthResult` — a plain dict with `data` and `error` keys. Check `result["error"]` first; if it's `None` the operation succeeded.
+
+---
+
+## Core Concepts
+
+### PyAuth
+
+`PyAuth` is the central manager. It holds your adapter and providers and exposes async methods for every auth flow.
+
+```
+PyAuth
+ ├── adapter          ← talks to your database
+ ├── providers        ← one or more auth strategies
+ └── cookies          ← merged cookie configuration
+```
+
+### Providers
+
+A **provider** encapsulates a single authentication strategy. `py-auth-core` ships with one built-in provider today, with more on the way:
+
+| Provider | Status | Description |
+|---|---|---|
+| `CredentialsProvider` | ✅ Available | Field-based sign-in (email/password, etc.) via a Pydantic model + async callback |
+| `GoogleProvider` | 🔜 Coming soon | Google OAuth 2.0 |
+| `GithubProvider` | 🔜 Coming soon | GitHub OAuth |
+| `EmailProvider` | 🔜 Coming soon | Passwordless magic-link sign-in |
+
+### Adapters
+
+An **adapter** is any object that satisfies `PyAuthAdapterProtocol`. It handles all database I/O: creating sessions, updating sessions and looking up / deleting sessions.
+
+`py-auth-core` validates your adapter at startup using a structural `Protocol` check — you'll get a clear `ConfigurationError` immediately if a required method is missing, rather than a cryptic failure later.
+
+See [Available Adapters](#available-adapters) for ready-made options.
+
+### Cookies
+
+`py-auth-core` manages two cookies:
+
+| Cookie | Default name | Purpose |
+|---|---|---|
+| Session token | `__Host-py_auth_session` | Authenticates the session — `httpOnly`, `Secure`, `SameSite=lax` |
+| CSRF token | `py_auth_csrf` | Double-submit CSRF protection — JavaScript-readable (no `httpOnly`) |
+
+Defaults are environment-aware: `secure=True` is always enforced when `ENVIRONMENT=production`. Override any value via `PyAuthCookiesInput`:
+
+```python
+from py_auth import PyAuth, PyAuthCookiesInput, CookieConfig, CookieOptions
+
+auth = PyAuth(
+    adapter=my_adapter,
+    providers=[credentials_provider],
+    cookies=PyAuthCookiesInput(
+        session_token=CookieConfig(
+            name="my_session",
+            options=CookieOptions(max_age=7 * 24 * 60 * 60),  # 7 days
+        )
+    ),
+)
+```
+
+---
+
+## API Reference
+
+### `PyAuth` class
+
+```python
+PyAuth(
+    adapter: PyAuthAdapterProtocol,
+    providers: list[BaseProvider] | None = None,
+    cookies: PyAuthCookiesInput | None = None,
+)
+```
+
+**Attributes**
+
+| Attribute | Type | Description |
+|---|---|---|
+| `adapter` | `PyAuthAdapterProtocol` | The validated adapter instance |
+| `cookies` | `dict[str, dict]` | Merged cookie config (name + options per token) |
+
+---
+
+#### `await auth.signin_with_credentials(request_body: dict) -> AuthResult`
+
+Validates `request_body` with the `CredentialsProvider`'s Pydantic model, calls your `authorize` callback, creates a session, and returns tokens.
+
+```python
+result = await auth.signin_with_credentials({"email": "...", "password": "..."})
+# Success:
+# result["data"] = {"session_token": "...", "csrf_token": "...", "user": {...}}
+# result["error"] = None
+#
+# Failure:
+# result["data"] = None
+# result["error"] = {"code": "CredentialsSignIn", "status_code": 401, "message": "..."}
+```
+
+---
+
+#### `await auth.verify_session(session_token: str, csrf_token: str) -> AuthResult`
+
+Hashes the session token, fetches the session from the adapter, checks expiry, and validates the CSRF token with `hmac.compare_digest`.
+
+```python
+result = await auth.verify_session(session_token, csrf_token)
+# Success:  result["data"] = {"session": {...}}
+# Failure:  result["error"] = {"code": "SessionExpired" | "InvalidCsrfToken" | ..., ...}
+```
+
+---
+
+#### `await auth.signout(session_id: str) -> AuthResult`
+
+Deletes the session identified by `session_id`.
+
+```python
+result = await auth.signout(session_id)
+# result["data"] = {"signed_out": True}
+```
+
+---
+
+#### `auth.get_auth_result(data=None, error=None) -> AuthResult`
+
+Utility to build a standardised `AuthResult`. Useful in custom middleware or route guards.
+
+---
+
+### `CredentialsProvider`
+
+```python
+CredentialsProvider(
+    model: Type[BaseModel],
+    authorize: Callable[[dict], Any] | Callable[[dict], Awaitable[Any]],
+)
+```
+
+| Parameter | Type | Description |
+|---|---|---|
+| `model` | `Type[BaseModel]` | Pydantic v2 model — the request body is validated against this before `authorize` is called |
+| `authorize` | sync or async callable | Receives the validated payload as a plain `dict`. Return a truthy user dict on success, or `None` / falsy to trigger a `401` |
+
+**Validation errors** are automatically serialised into a structured `422` response:
+
+```json
+{
+  "error": {
+    "code": "ValidationError",
+    "status_code": 422,
+    "message": "Validation failed.",
+    "details": {
+      "validation_errors": [
+        {"field": "email", "errors": ["value is not a valid email address"]}
+      ]
+    }
+  }
+}
+```
+
+---
+
+### `BaseProvider`
+
+Abstract base class for all providers. Every provider that ships with `py-auth` extends this class. The `id` attribute is automatically derived from the class name (lowercased, with `"provider"` stripped) — e.g. `CredentialsProvider` → `"credentials"`.
+
+```python
+from py_auth import BaseProvider, AuthResult
+
+
+class MyProvider(BaseProvider):
+    async def handle_request(self, *args, **kwargs) -> AuthResult: ...
+```
+
+---
+
+### Schemas & TypedDicts
+
+#### `AuthResult`
+```python
+class AuthResult(TypedDict):
+    data: Any | None
+    error: AuthError | None
+```
+
+#### `AuthError`
+```python
+class AuthError(TypedDict, total=False):
+    code: str  # machine-readable, e.g. "InvalidSessionToken"
+    status_code: int  # HTTP status to send to the client
+    message: str  # human-readable description
+    details: dict  # optional structured detail (e.g. validation errors)
+```
+
+#### `PyAuthAdapterProtocol`
+```python
+class PyAuthAdapterProtocol(Protocol):
+    async def create_session(self, session_data: dict) -> dict: ...
+    async def get_session_by_session_token_hash(
+        self, token_hash: str 
+    ) -> dict | None: ...
+    async def delete_session_by_session_token_hash(self, token_hash: str) -> None: ...
+    async def delete_session(self, session_id: str) -> None: ...
+    async def update_session(
+        self, session_id: str, updates: Dict
+    ) -> dict | None: ...
+```
+
+> The adapter only manages sessions. User lookup and creation live entirely inside your
+> `authorize()` callback — giving you full control over hashing, validation, and
+> any other user-creation logic your app needs.
+
+#### `CookieOptions`
+```python
+class CookieOptions(BaseModel):
+    http_only: bool | None = None
+    secure: bool | None = None
+    same_site: Literal["lax", "strict", "none"] | None = None
+    path: str | None = None
+    domain: str | None = None
+    max_age: int | None = None  # seconds
+    expires: datetime | None = None
+```
+
+---
+
+### Exceptions
+
+All exceptions inherit from `PyAuthError` and carry a `status_code` attribute for easy HTTP mapping.
+
+| Exception | Default `status_code` | When raised |
+|---|---|---|
+| `PyAuthError` | `500` | Base class; general catch-all |
+| `ConfigurationError` | `500` | Adapter missing required methods, or provider not configured |
+| `AdapterError` | `500` | Database engine setup failure |
+| `DuplicateEntryError` | `409` | Unique constraint violation (e.g. duplicate session token) |
+| `ForeignKeyViolationError` | `400` | Foreign key violation (e.g. referenced user no longer exists) |
+| `RecordNotFoundError` | `404` | Requested record not found |
+
+---
+
+## Integrations
+
+### FastAPI — `py-auth-fastapi`
+
+The official FastAPI integration is a separate package that removes all the boilerplate of wiring `py-auth-core` into a FastAPI app. **It's a single line.**
+
+You still configure the pieces you own — your providers and your `PyAuth` instance — and the integration handles everything else internally: mounting the auth routes, setting and reading cookies, and returning the right HTTP responses.
+
+```python
+# You set up your PyAuth instance as normal...
+auth = PyAuth(adapter=my_adapter, providers=[credentials_provider])
+
+# ...then hand it to the integration. That's it.
+app.include_router(PyAuthFastAPI(auth), prefix="/auth", tags=["Authentication"])
+```
+
+The integration exposes ready-made routes for sign-in, session verification, and sign-out — no manual cookie handling, no manual response construction.
+
+```bash
+pip install py-auth-fastapi
+```
+
+---
+
+## Available Adapters
+
+| Package | Supported Databases | Install |
+|---|---|---|
+| [`py-auth-sqlalchemy`](https://pypi.org/project/py-auth-sqlalchemy/) | PostgreSQL (`asyncpg`), MySQL (`aiomysql`), SQLite (`aiosqlite`) | `pip install py-auth-sqlalchemy` |
+
+> More adapters (Tortoise ORM, Motor/MongoDB, Beanie, etc.) are on the roadmap. Community contributions are welcome — see [CONTRIBUTING.md](./CONTRIBUTING.md).
+
+---
+
+## Roadmap
+
+`py-auth-core` is in early release (`0.0.1`). Here's what's planned:
+
+**Providers**
+- [ ] `GoogleProvider` — Google OAuth 2.0
+- [ ] `GithubProvider` — GitHub OAuth
+- [ ] `EmailProvider` — passwordless magic-link sign-in
+
+**Integrations**
+- [x] `py-auth-fastapi` — FastAPI integration
+- [ ] `py-auth-django` — Django integration
+- [ ] `py-auth-flask` — Flask / Quart integration
+- [ ] `py-auth-litestar` — Litestar integration
+
+**Adapters**
+- [ ] Tortoise ORM adapter
+- [ ] Motor (async MongoDB) adapter
+- [ ] Beanie adapter
+
+These will land as the project gains traction. If you'd like to see something added sooner, open an issue or a PR on [GitHub](https://github.com/jamaldeen09/py-auth).
+
+---
+
+## Security Notes
+
+- **Session tokens are never stored in plain text.** Only a SHA-256 hex digest is persisted; the raw token lives only in the client cookie.
+- **CSRF validation uses `hmac.compare_digest`** — immune to timing attacks.
+- **Cookie defaults follow the `__Host-` prefix convention** for session cookies: `Secure`, `httpOnly`, `Path=/`, no explicit `Domain`. This provides the strongest possible same-origin binding.
+- The **CSRF cookie intentionally omits `httpOnly`** so your frontend can read it and attach it as a request header for server-side comparison.
+- In `ENVIRONMENT=production`, the `secure` flag is always forced to `True` on every cookie regardless of user configuration.
+
+---
+
+## Contributing
+
+Want to build a new provider, adapter, or integration? See [CONTRIBUTING.md](./CONTRIBUTING.md) for architecture guidelines, how the adapter protocol works, and how to get started.
+
+---
+
+## License
+
+MIT — see [LICENSE](./LICENSE) for details.

py_auth_core-0.0.1.dist-info/RECORD

@@ -0,0 +1,14 @@
+py_auth/__init__.py,sha256=W6UQ3bM3k6D_6UT0K6E4UdTEyaHTMLFlbI2Es8N38EU,945
+py_auth/base.py,sha256=aYh_9MYUONzd6K169ESy-u680EtAxSo9zMJjU_RnOfk,443
+py_auth/core.py,sha256=DbR9hDHSEVqdQ6BU-Qm4gQPOYtxO6V710X-ecz7CX0g,9388
+py_auth/exceptions.py,sha256=xOqeqYz0x_jYR2iuozzGh9G0nOM7kZWFlCP_ZsaIBYg,1285
+py_auth/py.typed,sha256=bWew9mHgMy8LqMu7RuqQXFXLBxh2CRx0dUbSx-3wE48,27
+py_auth/schemas.py,sha256=c1hqN9GbCnVTe9jC_W6hFE_U-zZMn8oGwN-Nns3-Foo,2368
+py_auth/utils.py,sha256=uJow2o_fA99tlYQkG2DOewdI1_KQCJt_ttYRofAE80k,3284
+py_auth/providers/__init__.py,sha256=nU_2dYT9DqSpW9z2wR3zkwvxz1Y5nYtEFDMNmXGc9z0,164
+py_auth/providers/credentials.py,sha256=JI2KyeKGSYhzeDiKNqjYoGE4pjwMiTkPUKGIiEDErG0,2792
+py_auth_core-0.0.1.dist-info/licenses/LICENSE,sha256=I-lV8EG8M1xQi7woapfebjyhp5CiY-QESJVVf4yur24,1078
+py_auth_core-0.0.1.dist-info/METADATA,sha256=U10iL6GUhKn6UVwfXzurqg_lO1x38oyhoNqDxyiW5c0,15560
+py_auth_core-0.0.1.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+py_auth_core-0.0.1.dist-info/top_level.txt,sha256=7eMpqeN-eJJPiFjT3w9KcqO90D_RLQ7p1BN50041Jko,8
+py_auth_core-0.0.1.dist-info/RECORD,,

py_auth_core-0.0.1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

py_auth_core-0.0.1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) [2026] [Olatunji Jamaldeen]
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

py_auth_core-0.0.1.dist-info/top_level.txt

@@ -0,0 +1 @@
+py_auth