better-auth-server 0.1.0__py3-none-any.whl

better_auth/__init__.py

@@ -0,0 +1,40 @@
+"""better-auth-py: framework-agnostic authentication for Python.
+
+A port of `better-auth <https://better-auth.com>`_ with a FastAPI integration.
+"""
+
+from .adapters import BaseAdapter, MemoryAdapter, Where
+from .auth import BetterAuth
+from .config import EmailAndPassword, EmailVerification, RateLimit, SessionOptions
+from .oauth import Discord, GitHub, Google, OAuthProvider, OAuthTokens, OAuthUserInfo
+from .plugins import Plugin
+from .schema import CORE_SCHEMA, Field, Schema
+from .types import APIError, AuthRequest, AuthResponse, Ctx
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "CORE_SCHEMA",
+    "APIError",
+    "AuthRequest",
+    "AuthResponse",
+    "BaseAdapter",
+    "BetterAuth",
+    "Ctx",
+    "Discord",
+    "EmailAndPassword",
+    "EmailVerification",
+    "Field",
+    "GitHub",
+    "Google",
+    "MemoryAdapter",
+    "OAuthProvider",
+    "OAuthTokens",
+    "OAuthUserInfo",
+    "Plugin",
+    "RateLimit",
+    "Schema",
+    "SessionOptions",
+    "Where",
+    "__version__",
+]

better_auth/adapters/__init__.py

@@ -0,0 +1,4 @@
+from .base import BaseAdapter, Where
+from .memory import MemoryAdapter
+
+__all__ = ["BaseAdapter", "MemoryAdapter", "Where"]

better_auth/adapters/base.py

@@ -0,0 +1,44 @@
+"""Database adapter interface: generic CRUD over named models, like better-auth adapters.
+
+Rows are plain dicts with camelCase keys matching better_auth.schema. Plugins can define
+their own models without adapter changes.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from ..schema import Schema
+
+
+class Where:
+    """A single condition. operator: eq | ne | in | contains | gt | gte | lt | lte."""
+
+    __slots__ = ("field", "operator", "value")
+
+    def __init__(self, field: str, value: Any, operator: str = "eq"):
+        self.field = field
+        self.value = value
+        self.operator = operator
+
+
+class BaseAdapter:
+    def init(self, schema: Schema) -> None:
+        """Called once by BetterAuth with the merged (core + plugins) schema."""
+
+    async def create(self, model: str, data: dict[str, Any]) -> dict[str, Any]:
+        raise NotImplementedError
+
+    async def find_one(self, model: str, where: list[Where]) -> dict[str, Any] | None:
+        raise NotImplementedError
+
+    async def find_many(self, model: str, where: list[Where] | None = None) -> list[dict[str, Any]]:
+        raise NotImplementedError
+
+    async def update(
+        self, model: str, where: list[Where], data: dict[str, Any]
+    ) -> dict[str, Any] | None:
+        raise NotImplementedError
+
+    async def delete_many(self, model: str, where: list[Where]) -> int:
+        raise NotImplementedError

better_auth/adapters/memory.py

@@ -0,0 +1,55 @@
+"""In-memory adapter for development and tests."""
+
+from __future__ import annotations
+
+from collections import defaultdict
+from collections.abc import Callable
+from typing import Any
+
+from .base import BaseAdapter, Where
+
+_OPS: dict[str, Callable[[Any, Any], bool]] = {
+    "eq": lambda a, b: a == b,
+    "ne": lambda a, b: a != b,
+    "in": lambda a, b: a in b,
+    "contains": lambda a, b: isinstance(a, str) and b in a,
+    "gt": lambda a, b: a is not None and a > b,
+    "gte": lambda a, b: a is not None and a >= b,
+    "lt": lambda a, b: a is not None and a < b,
+    "lte": lambda a, b: a is not None and a <= b,
+}
+
+
+def _matches(row: dict[str, Any], where: list[Where] | None) -> bool:
+    return all(_OPS[c.operator](row.get(c.field), c.value) for c in where or [])
+
+
+class MemoryAdapter(BaseAdapter):
+    def __init__(self) -> None:
+        self._store: dict[str, list[dict[str, Any]]] = defaultdict(list)
+
+    async def create(self, model: str, data: dict[str, Any]) -> dict[str, Any]:
+        self._store[model].append(dict(data))
+        return dict(data)
+
+    async def find_one(self, model: str, where: list[Where]) -> dict[str, Any] | None:
+        return next((dict(r) for r in self._store[model] if _matches(r, where)), None)
+
+    async def find_many(self, model: str, where: list[Where] | None = None) -> list[dict[str, Any]]:
+        return [dict(r) for r in self._store[model] if _matches(r, where)]
+
+    async def update(
+        self, model: str, where: list[Where], data: dict[str, Any]
+    ) -> dict[str, Any] | None:
+        for row in self._store[model]:
+            if _matches(row, where):
+                row.update(data)
+                return dict(row)
+        return None
+
+    async def delete_many(self, model: str, where: list[Where]) -> int:
+        rows = self._store[model]
+        kept = [r for r in rows if not _matches(r, where)]
+        deleted = len(rows) - len(kept)
+        self._store[model] = kept
+        return deleted

better_auth/adapters/sqlalchemy.py

@@ -0,0 +1,166 @@
+"""SQLAlchemy adapter (async). Tables are generated from the merged schema.
+
+Install with: ``pip install better-auth-py[sqlalchemy]``.
+
+Datetimes are stored as naive UTC (portable across SQLite/Postgres/MySQL) and always
+returned timezone-aware (UTC).
+"""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from typing import Any
+
+from sqlalchemy import Boolean, Column, DateTime, ForeignKey, MetaData, String, Table, Text, and_
+from sqlalchemy.ext.asyncio import AsyncEngine
+from sqlalchemy.sql import ColumnElement
+
+from ..schema import Schema
+from .base import BaseAdapter, Where
+
+_TYPES = {
+    "string": lambda: String(255),
+    "text": lambda: Text(),
+    "boolean": lambda: Boolean(),
+    "datetime": lambda: DateTime(),
+}
+
+
+def _to_storage(value: Any) -> Any:
+    if isinstance(value, datetime) and value.tzinfo is not None:
+        return value.astimezone(timezone.utc).replace(tzinfo=None)
+    return value
+
+
+def _from_storage(value: Any) -> Any:
+    if isinstance(value, datetime) and value.tzinfo is None:
+        return value.replace(tzinfo=timezone.utc)
+    return value
+
+
+class SQLAlchemyAdapter(BaseAdapter):
+    def __init__(self, engine: AsyncEngine, metadata: MetaData | None = None):
+        self.engine = engine
+        self.metadata = metadata or MetaData()
+        self._tables: dict[str, Table] = {}
+
+    def init(self, schema: Schema) -> None:
+        for model, fields in schema.items():
+            if model in self._tables:
+                continue
+            columns: list[Column] = []
+            for name, spec in fields.items():
+                args: list[Any] = [_TYPES[spec.type]()]
+                if spec.references:
+                    ref_model, ref_col = spec.references.split(".")
+                    args.append(ForeignKey(f"{ref_model}.{ref_col}"))
+                columns.append(
+                    Column(
+                        name,
+                        *args,
+                        primary_key=name == "id",
+                        nullable=not spec.required,
+                        unique=spec.unique and name != "id",
+                    )
+                )
+            self._tables[model] = Table(model, self.metadata, *columns)
+
+    async def create_tables(self) -> None:
+        """Create missing tables (dev convenience — use real migrations in production)."""
+        async with self.engine.begin() as conn:
+            await conn.run_sync(self.metadata.create_all)
+
+    def _table(self, model: str) -> Table:
+        try:
+            return self._tables[model]
+        except KeyError:
+            raise KeyError(f"Unknown model {model!r} — was the adapter initialized?") from None
+
+    def _condition(self, table: Table, where: list[Where] | None) -> ColumnElement | None:
+        if not where:
+            return None
+        parts = []
+        for c in where:
+            col = table.c[c.field]
+            value = _to_storage(c.value)
+            if c.operator == "eq":
+                parts.append(col == value)
+            elif c.operator == "ne":
+                parts.append(col != value)
+            elif c.operator == "in":
+                parts.append(col.in_([_to_storage(v) for v in c.value]))
+            elif c.operator == "contains":
+                parts.append(col.contains(c.value))
+            elif c.operator == "gt":
+                parts.append(col > value)
+            elif c.operator == "gte":
+                parts.append(col >= value)
+            elif c.operator == "lt":
+                parts.append(col < value)
+            elif c.operator == "lte":
+                parts.append(col <= value)
+            else:
+                raise ValueError(f"Unsupported operator {c.operator!r}")
+        return and_(*parts)
+
+    @staticmethod
+    def _row(row: Any) -> dict[str, Any]:
+        return {key: _from_storage(value) for key, value in row._mapping.items()}
+
+    async def create(self, model: str, data: dict[str, Any]) -> dict[str, Any]:
+        table = self._table(model)
+        values = {k: _to_storage(v) for k, v in data.items()}
+        async with self.engine.begin() as conn:
+            await conn.execute(table.insert().values(**values))
+        return dict(data)
+
+    async def find_one(self, model: str, where: list[Where]) -> dict[str, Any] | None:
+        table = self._table(model)
+        stmt = table.select().limit(1)
+        cond = self._condition(table, where)
+        if cond is not None:
+            stmt = stmt.where(cond)
+        async with self.engine.connect() as conn:
+            row = (await conn.execute(stmt)).first()
+        return self._row(row) if row is not None else None
+
+    async def find_many(self, model: str, where: list[Where] | None = None) -> list[dict[str, Any]]:
+        table = self._table(model)
+        stmt = table.select()
+        cond = self._condition(table, where)
+        if cond is not None:
+            stmt = stmt.where(cond)
+        async with self.engine.connect() as conn:
+            rows = (await conn.execute(stmt)).all()
+        return [self._row(r) for r in rows]
+
+    async def update(
+        self, model: str, where: list[Where], data: dict[str, Any]
+    ) -> dict[str, Any] | None:
+        table = self._table(model)
+        cond = self._condition(table, where)
+        values = {k: _to_storage(v) for k, v in data.items()}
+        stmt = table.update().values(**values)
+        if cond is not None:
+            stmt = stmt.where(cond)
+        async with self.engine.begin() as conn:
+            await conn.execute(stmt)
+        return await self.find_one(model, self._refind(where, data))
+
+    @staticmethod
+    def _refind(where: list[Where], data: dict[str, Any]) -> list[Where]:
+        # if an updated column was part of the lookup, look it up by its new value
+        return [
+            Where(c.field, data[c.field]) if c.operator == "eq" and c.field in data else c
+            for c in where
+        ]
+
+    async def delete_many(self, model: str, where: list[Where]) -> int:
+        table = self._table(model)
+        cond = self._condition(table, where)
+        stmt = table.delete()
+        if cond is not None:
+            stmt = stmt.where(cond)
+        async with self.engine.begin() as conn:
+            result = await conn.execute(stmt)
+        return int(result.rowcount or 0)

better_auth/auth.py

@@ -0,0 +1,239 @@
+"""BetterAuth: configuration, routing and request dispatch."""
+
+from __future__ import annotations
+
+import logging
+import time
+from collections.abc import Awaitable, Callable, Mapping
+from typing import Any
+from urllib.parse import urlsplit
+
+import httpx
+
+from .adapters.base import BaseAdapter
+from .adapters.memory import MemoryAdapter
+from .config import EmailAndPassword, EmailVerification, RateLimit, SessionOptions
+from .endpoints import ROUTES
+from .oauth import OAuthProvider
+from .plugins import Plugin
+from .schema import CORE_SCHEMA, Schema, merge_schema
+from .session import get_session as _get_session
+from .types import APIError, AuthRequest, AuthResponse, Ctx
+
+logger = logging.getLogger("better_auth")
+
+# better-auth's default special rate-limit rules: (window seconds, max requests)
+_SPECIAL_RATE_RULES: list[tuple[Callable[[str], bool], tuple[int, int]]] = [
+    (
+        lambda p: p.startswith(("/sign-in", "/sign-up", "/change-password", "/change-email")),
+        (10, 3),
+    ),
+    (
+        lambda p: (
+            p in ("/request-password-reset", "/send-verification-email")
+            or p.startswith("/forget-password")
+        ),
+        (60, 3),
+    ),
+]
+
+
+class BetterAuth:
+    """The auth instance. Mount it with an integration (e.g. better_auth.integrations.fastapi)
+    or call :meth:`handle` with an :class:`~better_auth.types.AuthRequest` directly."""
+
+    def __init__(
+        self,
+        *,
+        secret: str,
+        adapter: BaseAdapter | None = None,
+        base_url: str = "http://localhost:8000",
+        base_path: str = "/api/auth",
+        email_and_password: EmailAndPassword | None = None,
+        email_verification: EmailVerification | None = None,
+        social_providers: Mapping[str, OAuthProvider] | None = None,
+        session: SessionOptions | None = None,
+        rate_limit: RateLimit | None = None,
+        trusted_origins: list[str] | None = None,
+        plugins: list[Plugin] | None = None,
+        hooks: dict[str, Callable[..., Awaitable[None]]] | None = None,
+        http_client: httpx.AsyncClient | None = None,
+        cookie_prefix: str = "better-auth",
+        use_secure_cookies: bool | None = None,
+        skip_state_cookie_check: bool = False,
+    ):
+        if not secret or len(secret) < 32:
+            raise ValueError(
+                "secret must be at least 32 characters — generate one with"
+                " `openssl rand -base64 32`"
+            )
+        self.secret = secret
+        self.base_url = base_url.rstrip("/")
+        stripped = base_path.strip("/")
+        self.base_path = f"/{stripped}" if stripped else ""
+        self.email_and_password = email_and_password or EmailAndPassword()
+        self.email_verification = email_verification or EmailVerification()
+        self.session_options = session or SessionOptions()
+        self.rate_limit = rate_limit or RateLimit()
+        self.trusted_origins = [origin.rstrip("/") for origin in trusted_origins or []]
+        self.plugins = list(plugins or [])
+        self.hooks = dict(hooks or {})
+        self.cookie_prefix = cookie_prefix
+        self.use_secure_cookies = (
+            use_secure_cookies
+            if use_secure_cookies is not None
+            else self.base_url.startswith("https://")
+        )
+        self.skip_state_cookie_check = skip_state_cookie_check
+
+        self.social_providers = dict(social_providers or {})
+        for provider_id, provider in self.social_providers.items():
+            if not provider.provider_id:
+                provider.provider_id = provider_id
+
+        self.schema: Schema = merge_schema(CORE_SCHEMA, *(p.schema for p in self.plugins))
+        self.adapter = adapter if adapter is not None else MemoryAdapter()
+        self.adapter.init(self.schema)
+
+        self._http = http_client
+        self._rate_buckets: dict[str, tuple[float, int]] = {}
+        self._routes: list[tuple[str, tuple[str, ...], Any]] = []
+        for method, path, handler in [
+            *ROUTES,
+            *(route for plugin in self.plugins for route in plugin.routes()),
+        ]:
+            self._routes.append((method, tuple(path.strip("/").split("/")), handler))
+
+    # --- helpers ----------------------------------------------------------------------
+
+    @property
+    def http(self) -> httpx.AsyncClient:
+        if self._http is None:
+            self._http = httpx.AsyncClient(timeout=10)
+        return self._http
+
+    async def run_hook(self, name: str, *args: Any) -> None:
+        hook = self.hooks.get(name)
+        if hook is not None:
+            await hook(*args)
+
+    def _allowed_origins(self) -> set[str]:
+        origins = {self._origin(self.base_url)}
+        origins.update(self._origin(origin) for origin in self.trusted_origins)
+        origins.discard("")
+        return origins
+
+    @staticmethod
+    def _origin(url: str) -> str:
+        parts = urlsplit(url)
+        return f"{parts.scheme}://{parts.netloc}" if parts.scheme and parts.netloc else ""
+
+    def is_trusted_url(self, url: str) -> bool:
+        """Relative paths and URLs on the base/trusted origins are allowed redirect targets."""
+        if url.startswith("/") and not url.startswith("//"):
+            return True
+        return self._origin(url) in self._allowed_origins()
+
+    def ensure_trusted_url(self, url: str) -> None:
+        if not self.is_trusted_url(url):
+            raise APIError(403, "INVALID_CALLBACK_URL", "Callback URL is not trusted")
+
+    async def load_session(self, request: AuthRequest) -> dict[str, Any] | None:
+        """``{"session": ..., "user": ...}`` for the request, or None. Used by integrations."""
+        result, _cookies = await _get_session(self, request)
+        return result
+
+    # --- dispatch ---------------------------------------------------------------------
+
+    async def handle(self, request: AuthRequest) -> AuthResponse:
+        try:
+            return await self._dispatch(request)
+        except APIError as error:
+            return AuthResponse(
+                status=error.status, body={"code": error.code, "message": error.message}
+            )
+        except Exception:
+            logger.exception("better-auth error handling %s %s", request.method, request.path)
+            return AuthResponse(status=500, body={"message": "Internal Server Error"})
+
+    async def _dispatch(self, request: AuthRequest) -> AuthResponse:
+        request.path = "/" + request.path.strip("/")
+
+        retry_after = self._check_rate_limit(request)
+        if retry_after is not None:
+            return AuthResponse(
+                status=429,
+                body={"message": "Too many requests. Please try again later."},
+                headers=[("x-retry-after", str(retry_after))],
+            )
+        self._check_origin(request)
+
+        match = self._match(request.method, request.path)
+        if match is None:
+            return AuthResponse(status=404, body={"message": "Not Found"})
+        handler, params = match
+
+        ctx = Ctx(auth=self, request=request, params=params)
+        for plugin in self.plugins:
+            short_circuit = await plugin.before(ctx)
+            if short_circuit is not None:
+                return short_circuit
+
+        result = await handler(ctx)
+        response = result if isinstance(result, AuthResponse) else AuthResponse(body=result)
+
+        for plugin in self.plugins:
+            replacement = await plugin.after(ctx, response)
+            if replacement is not None:
+                response = replacement
+        return response
+
+    def _match(self, method: str, path: str) -> tuple[Any, dict[str, str]] | None:
+        parts = tuple(path.strip("/").split("/"))
+        for route_method, segments, handler in self._routes:
+            if route_method != method or len(segments) != len(parts):
+                continue
+            params: dict[str, str] = {}
+            for segment, part in zip(segments, parts, strict=True):
+                if segment.startswith("{") and segment.endswith("}"):
+                    params[segment[1:-1]] = part
+                elif segment != part:
+                    break
+            else:
+                return handler, params
+        return None
+
+    def _check_origin(self, request: AuthRequest) -> None:
+        """Reject state-changing requests from untrusted browser origins (CSRF)."""
+        if request.method == "GET":
+            return
+        origin = request.headers.get("origin")
+        if not origin:  # non-browser clients (no Origin header) pass through
+            return
+        if origin.rstrip("/") not in self._allowed_origins():
+            raise APIError(403, "INVALID_ORIGIN", "Origin not trusted")
+
+    def _check_rate_limit(self, request: AuthRequest) -> int | None:
+        """Returns seconds to wait when limited, else None. Fixed window, in-memory."""
+        limit = self.rate_limit
+        if not limit.enabled:
+            return None
+        window, maximum = limit.window, limit.max
+        for matches, rule in _SPECIAL_RATE_RULES:
+            if matches(request.path):
+                window, maximum = rule
+                break
+        custom = limit.custom_rules.get(request.path)
+        if custom is not None:
+            window, maximum = custom
+
+        key = f"{request.client_ip or 'no-ip'}-{request.path}"
+        now = time.time()
+        start, count = self._rate_buckets.get(key, (now, 0))
+        if now - start >= window:
+            start, count = now, 0
+        count += 1
+        self._rate_buckets[key] = (start, count)
+        if count > maximum:
+            return max(1, int(window - (now - start)))
+        return None

better_auth/config.py

@@ -0,0 +1,55 @@
+"""Configuration dataclasses, mirroring better-auth's options."""
+
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass, field
+from typing import Any
+
+#: async callback(user, url, token) used for verification / reset-password emails.
+SendEmail = Callable[[dict[str, Any], str, str], Awaitable[None]]
+
+DAY = 60 * 60 * 24
+
+
+@dataclass
+class EmailAndPassword:
+    enabled: bool = False
+    min_password_length: int = 8
+    max_password_length: int = 128
+    require_email_verification: bool = False
+    #: create a session right after sign-up (ignored when email verification is required)
+    auto_sign_in: bool = True
+    send_reset_password: SendEmail | None = None
+    reset_password_token_expires_in: int = 60 * 60
+    revoke_sessions_on_password_reset: bool = False
+
+
+@dataclass
+class EmailVerification:
+    send_verification_email: SendEmail | None = None
+    send_on_sign_up: bool = False
+    auto_sign_in_after_verification: bool = False
+    expires_in: int = 60 * 60
+
+
+@dataclass
+class SessionOptions:
+    expires_in: int = 7 * DAY
+    #: refresh `expiresAt` when the session is older than this
+    update_age: int = 1 * DAY
+
+
+@dataclass
+class RateLimit:
+    """Fixed-window in-memory rate limiting, keyed by client IP + path.
+
+    ponytail: in-memory only — use one worker or put stricter limits at the proxy;
+    a shared-storage backend can come later if needed.
+    """
+
+    enabled: bool = False
+    window: int = 10  # seconds
+    max: int = 100
+    #: per-path overrides, e.g. {"/sign-in/email": (10, 3)}
+    custom_rules: dict[str, tuple[int, int]] = field(default_factory=dict)