belgie 0.1.0__tar.gz

belgie-0.1.0/PKG-INFO

@@ -0,0 +1,231 @@
+Metadata-Version: 2.3
+Name: belgie
+Version: 0.1.0
+Summary: Modern authentication for FastAPI
+Author: Matt LeMay
+Author-email: Matt LeMay <mplemay@users.noreply.github.com>
+Requires-Dist: belgie-proto
+Requires-Dist: fastapi>=0.100
+Requires-Dist: httpx>=0.24
+Requires-Dist: pydantic>=2.0
+Requires-Dist: pydantic-settings>=2.0
+Requires-Dist: python-multipart>=0.0.20
+Requires-Dist: belgie-alchemy ; extra == 'alchemy'
+Requires-Dist: belgie-alchemy ; extra == 'all'
+Requires-Dist: belgie-mcp ; extra == 'all'
+Requires-Dist: belgie-oauth ; extra == 'all'
+Requires-Dist: uvicorn[standard]>=0.38.0 ; extra == 'examples'
+Requires-Dist: belgie-mcp ; extra == 'mcp'
+Requires-Dist: belgie-oauth ; extra == 'oauth'
+Requires-Python: >=3.12, <3.15
+Provides-Extra: alchemy
+Provides-Extra: all
+Provides-Extra: examples
+Provides-Extra: mcp
+Provides-Extra: oauth
+Description-Content-Type: text/markdown
+
+# Belgie
+
+Self-hosted, type-safe authentication for FastAPI that makes Google OAuth and secure session cookies work with almost
+zero glue code. Keep your data, skip per-user SaaS bills, and still get a polished developer experience.
+
+## Who this is for
+
+- FastAPI teams that want Google sign-in and protected routes today, not after weeks of wiring.
+- Product engineers who prefer first-class type hints and adapter-driven design over magic.
+- Startups that would rather own their user data and avoid per-MAU pricing from hosted identity vendors.
+
+## What it solves
+
+- End-to-end Google OAuth 2.0 flow with CSRF-safe state storage.
+- Sliding-window, signed session cookies (no JWT juggling required).
+- Drop-in FastAPI dependencies for `auth.user`, `auth.session`, and scoped access.
+- A thin SQLAlchemy adapter that works with your existing models.
+- Hooks so you can plug in logging, analytics, or audit trails without forking.
+
+## How it compares
+
+- **fastapi-users**: feature-rich but now in maintenance mode and optimized for password-plus-OAuth flows. Belgie
+  focuses on OAuth + session UX, keeps the surface area small, and ships type-driven adapters out of the box.
+- **Hosted identity (Auth0, Clerk, Supabase Auth)**: great UIs and more providers, but billed per Monthly Active User
+  and hosted off your stack. Belgie is MIT-licensed, runs in your app, and never charges per user.
+
+## Features at a glance
+
+- Google OAuth provider with ready-made router (`/auth/signin/google`, `/auth/callback/google`, `/auth/signout`).
+- Session manager with sliding expiry and secure cookie defaults (HttpOnly, SameSite, Secure).
+- Scope-aware dependency for route protection (`Security(auth.user, scopes=[...])`).
+- Modern Python (3.12+), full typing, and protocol-based models.
+- Event hooks and utility helpers for custom workflows.
+
+## Installation
+
+```bash
+pip install belgie
+# or with uv
+uv add belgie
+```
+
+For SQLAlchemy adapter support:
+
+```bash
+pip install belgie[alchemy]
+# or with uv
+uv add belgie[alchemy]
+```
+
+Optional extras: `belgie[mcp]`, `belgie[oauth]`, or `belgie[all]`.
+
+## Quick start
+
+### 1) Define models
+
+```python
+from datetime import UTC, datetime
+from uuid import UUID, uuid4
+from sqlalchemy import ForeignKey, String
+from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column
+
+
+class Base(DeclarativeBase):
+    pass
+
+
+class User(Base):
+    __tablename__ = "users"
+    id: Mapped[UUID] = mapped_column(primary_key=True, default=uuid4)
+    email: Mapped[str] = mapped_column(String(255), unique=True, index=True)
+    name: Mapped[str | None] = mapped_column(String(255), nullable=True)
+    image: Mapped[str | None] = mapped_column(String(500), nullable=True)
+    email_verified: Mapped[bool] = mapped_column(default=False)
+    created_at: Mapped[datetime] = mapped_column(default=lambda: datetime.now(UTC))
+    updated_at: Mapped[datetime] = mapped_column(default=lambda: datetime.now(UTC))
+
+
+class Account(Base):
+    __tablename__ = "accounts"
+    id: Mapped[UUID] = mapped_column(primary_key=True, default=uuid4)
+    user_id: Mapped[UUID] = mapped_column(ForeignKey("users.id", ondelete="CASCADE"))
+    provider: Mapped[str] = mapped_column(String(50))
+    provider_account_id: Mapped[str] = mapped_column(String(255))
+    access_token: Mapped[str | None] = mapped_column(String(1000), nullable=True)
+    refresh_token: Mapped[str | None] = mapped_column(String(1000), nullable=True)
+    expires_at: Mapped[datetime | None] = mapped_column(nullable=True)
+    scope: Mapped[str | None] = mapped_column(String(500), nullable=True)
+    created_at: Mapped[datetime] = mapped_column(default=lambda: datetime.now(UTC))
+
+
+class Session(Base):
+    __tablename__ = "sessions"
+    id: Mapped[UUID] = mapped_column(primary_key=True, default=uuid4)
+    user_id: Mapped[UUID] = mapped_column(ForeignKey("users.id", ondelete="CASCADE"))
+    expires_at: Mapped[datetime] = mapped_column(index=True)
+    created_at: Mapped[datetime] = mapped_column(default=lambda: datetime.now(UTC))
+
+
+class OAuthState(Base):
+    __tablename__ = "oauth_states"
+    id: Mapped[UUID] = mapped_column(primary_key=True, default=uuid4)
+    state: Mapped[str] = mapped_column(String(255), unique=True, index=True)
+    expires_at: Mapped[datetime] = mapped_column(index=True)
+    created_at: Mapped[datetime] = mapped_column(default=lambda: datetime.now(UTC))
+```
+
+### 2) Configure Belgie
+
+```python
+from belgie.auth import Auth, AuthSettings, GoogleProviderSettings
+from belgie_alchemy import AlchemyAdapter
+
+settings = AuthSettings(
+    secret="your-secret-key",
+    base_url="http://localhost:8000",
+)
+
+adapter = AlchemyAdapter(
+    user=User,
+    account=Account,
+    session=Session,
+    oauth_state=OAuthState,
+)
+
+auth = Auth(
+    settings=settings,
+    adapter=adapter,
+    providers={
+        "google": GoogleProviderSettings(
+            client_id="your-google-client-id",
+            client_secret="your-google-client-secret",
+            redirect_uri="http://localhost:8000/auth/provider/google/callback",
+            scopes=["openid", "email", "profile"],
+        ),
+    },
+)
+```
+
+### 3) Add routes to FastAPI
+
+```python
+from fastapi import Depends, FastAPI, Security
+
+app = FastAPI()
+app.include_router(auth.router)
+
+
+@app.get("/")
+async def home():
+    return {"message": "Welcome! Visit /auth/provider/google/signin to sign in"}
+
+
+@app.get("/protected")
+async def protected(user: User = Depends(auth.user)):
+    return {"email": user.email}
+
+
+@app.get("/profile")
+async def profile(user: User = Security(auth.user, scopes=["profile"])):
+    return {"name": user.name, "email": user.email}
+```
+
+Run it:
+
+```bash
+uvicorn main:app --reload
+```
+
+Visit `http://localhost:8000/auth/signin/google` to sign in.
+
+## Configuration shortcuts
+
+- Environment variables: `BELGIE_SECRET`, `BELGIE_BASE_URL`, `BELGIE_GOOGLE_CLIENT_ID`, `BELGIE_GOOGLE_CLIENT_SECRET`,
+  `BELGIE_GOOGLE_REDIRECT_URI` (loaded automatically by `AuthSettings()`).
+- Session tuning: `SessionSettings(cookie_name, max_age, update_age)` controls lifetime and sliding refresh.
+- Cookie hardening: `CookieSettings(http_only, secure, same_site)` for production-ready defaults.
+
+## Router endpoints
+
+- `GET /auth/signin/google` – start OAuth flow
+- `GET /auth/callback/google` – handle Google callback
+- `POST /auth/signout` – clear session cookie and invalidate server session
+
+## Limitations today
+
+- Google is the only built-in provider; more providers and email/password are on the roadmap.
+- You manage your own database migrations and deployment (by design—no third-party control plane).
+
+## Why teams pick Belgie
+
+- Keep control of data and infra while getting a batteries-included OAuth flow.
+- Minimal surface area: a single `Auth` instance exposes router + dependencies.
+- Modern typing and clear protocols reduce integration mistakes and make refactors safer.
+- MIT license, zero per-user costs.
+
+## Documentation and examples
+
+- [docs/quickstart.md](docs/quickstart.md) for full walkthrough
+- [examples/auth](examples/auth) for a runnable app
+
+## Contributing
+
+MIT licensed. Issues and PRs welcome.

belgie-0.1.0/README.md

@@ -0,0 +1,204 @@
+# Belgie
+
+Self-hosted, type-safe authentication for FastAPI that makes Google OAuth and secure session cookies work with almost
+zero glue code. Keep your data, skip per-user SaaS bills, and still get a polished developer experience.
+
+## Who this is for
+
+- FastAPI teams that want Google sign-in and protected routes today, not after weeks of wiring.
+- Product engineers who prefer first-class type hints and adapter-driven design over magic.
+- Startups that would rather own their user data and avoid per-MAU pricing from hosted identity vendors.
+
+## What it solves
+
+- End-to-end Google OAuth 2.0 flow with CSRF-safe state storage.
+- Sliding-window, signed session cookies (no JWT juggling required).
+- Drop-in FastAPI dependencies for `auth.user`, `auth.session`, and scoped access.
+- A thin SQLAlchemy adapter that works with your existing models.
+- Hooks so you can plug in logging, analytics, or audit trails without forking.
+
+## How it compares
+
+- **fastapi-users**: feature-rich but now in maintenance mode and optimized for password-plus-OAuth flows. Belgie
+  focuses on OAuth + session UX, keeps the surface area small, and ships type-driven adapters out of the box.
+- **Hosted identity (Auth0, Clerk, Supabase Auth)**: great UIs and more providers, but billed per Monthly Active User
+  and hosted off your stack. Belgie is MIT-licensed, runs in your app, and never charges per user.
+
+## Features at a glance
+
+- Google OAuth provider with ready-made router (`/auth/signin/google`, `/auth/callback/google`, `/auth/signout`).
+- Session manager with sliding expiry and secure cookie defaults (HttpOnly, SameSite, Secure).
+- Scope-aware dependency for route protection (`Security(auth.user, scopes=[...])`).
+- Modern Python (3.12+), full typing, and protocol-based models.
+- Event hooks and utility helpers for custom workflows.
+
+## Installation
+
+```bash
+pip install belgie
+# or with uv
+uv add belgie
+```
+
+For SQLAlchemy adapter support:
+
+```bash
+pip install belgie[alchemy]
+# or with uv
+uv add belgie[alchemy]
+```
+
+Optional extras: `belgie[mcp]`, `belgie[oauth]`, or `belgie[all]`.
+
+## Quick start
+
+### 1) Define models
+
+```python
+from datetime import UTC, datetime
+from uuid import UUID, uuid4
+from sqlalchemy import ForeignKey, String
+from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column
+
+
+class Base(DeclarativeBase):
+    pass
+
+
+class User(Base):
+    __tablename__ = "users"
+    id: Mapped[UUID] = mapped_column(primary_key=True, default=uuid4)
+    email: Mapped[str] = mapped_column(String(255), unique=True, index=True)
+    name: Mapped[str | None] = mapped_column(String(255), nullable=True)
+    image: Mapped[str | None] = mapped_column(String(500), nullable=True)
+    email_verified: Mapped[bool] = mapped_column(default=False)
+    created_at: Mapped[datetime] = mapped_column(default=lambda: datetime.now(UTC))
+    updated_at: Mapped[datetime] = mapped_column(default=lambda: datetime.now(UTC))
+
+
+class Account(Base):
+    __tablename__ = "accounts"
+    id: Mapped[UUID] = mapped_column(primary_key=True, default=uuid4)
+    user_id: Mapped[UUID] = mapped_column(ForeignKey("users.id", ondelete="CASCADE"))
+    provider: Mapped[str] = mapped_column(String(50))
+    provider_account_id: Mapped[str] = mapped_column(String(255))
+    access_token: Mapped[str | None] = mapped_column(String(1000), nullable=True)
+    refresh_token: Mapped[str | None] = mapped_column(String(1000), nullable=True)
+    expires_at: Mapped[datetime | None] = mapped_column(nullable=True)
+    scope: Mapped[str | None] = mapped_column(String(500), nullable=True)
+    created_at: Mapped[datetime] = mapped_column(default=lambda: datetime.now(UTC))
+
+
+class Session(Base):
+    __tablename__ = "sessions"
+    id: Mapped[UUID] = mapped_column(primary_key=True, default=uuid4)
+    user_id: Mapped[UUID] = mapped_column(ForeignKey("users.id", ondelete="CASCADE"))
+    expires_at: Mapped[datetime] = mapped_column(index=True)
+    created_at: Mapped[datetime] = mapped_column(default=lambda: datetime.now(UTC))
+
+
+class OAuthState(Base):
+    __tablename__ = "oauth_states"
+    id: Mapped[UUID] = mapped_column(primary_key=True, default=uuid4)
+    state: Mapped[str] = mapped_column(String(255), unique=True, index=True)
+    expires_at: Mapped[datetime] = mapped_column(index=True)
+    created_at: Mapped[datetime] = mapped_column(default=lambda: datetime.now(UTC))
+```
+
+### 2) Configure Belgie
+
+```python
+from belgie.auth import Auth, AuthSettings, GoogleProviderSettings
+from belgie_alchemy import AlchemyAdapter
+
+settings = AuthSettings(
+    secret="your-secret-key",
+    base_url="http://localhost:8000",
+)
+
+adapter = AlchemyAdapter(
+    user=User,
+    account=Account,
+    session=Session,
+    oauth_state=OAuthState,
+)
+
+auth = Auth(
+    settings=settings,
+    adapter=adapter,
+    providers={
+        "google": GoogleProviderSettings(
+            client_id="your-google-client-id",
+            client_secret="your-google-client-secret",
+            redirect_uri="http://localhost:8000/auth/provider/google/callback",
+            scopes=["openid", "email", "profile"],
+        ),
+    },
+)
+```
+
+### 3) Add routes to FastAPI
+
+```python
+from fastapi import Depends, FastAPI, Security
+
+app = FastAPI()
+app.include_router(auth.router)
+
+
+@app.get("/")
+async def home():
+    return {"message": "Welcome! Visit /auth/provider/google/signin to sign in"}
+
+
+@app.get("/protected")
+async def protected(user: User = Depends(auth.user)):
+    return {"email": user.email}
+
+
+@app.get("/profile")
+async def profile(user: User = Security(auth.user, scopes=["profile"])):
+    return {"name": user.name, "email": user.email}
+```
+
+Run it:
+
+```bash
+uvicorn main:app --reload
+```
+
+Visit `http://localhost:8000/auth/signin/google` to sign in.
+
+## Configuration shortcuts
+
+- Environment variables: `BELGIE_SECRET`, `BELGIE_BASE_URL`, `BELGIE_GOOGLE_CLIENT_ID`, `BELGIE_GOOGLE_CLIENT_SECRET`,
+  `BELGIE_GOOGLE_REDIRECT_URI` (loaded automatically by `AuthSettings()`).
+- Session tuning: `SessionSettings(cookie_name, max_age, update_age)` controls lifetime and sliding refresh.
+- Cookie hardening: `CookieSettings(http_only, secure, same_site)` for production-ready defaults.
+
+## Router endpoints
+
+- `GET /auth/signin/google` – start OAuth flow
+- `GET /auth/callback/google` – handle Google callback
+- `POST /auth/signout` – clear session cookie and invalidate server session
+
+## Limitations today
+
+- Google is the only built-in provider; more providers and email/password are on the roadmap.
+- You manage your own database migrations and deployment (by design—no third-party control plane).
+
+## Why teams pick Belgie
+
+- Keep control of data and infra while getting a batteries-included OAuth flow.
+- Minimal surface area: a single `Auth` instance exposes router + dependencies.
+- Modern typing and clear protocols reduce integration mistakes and make refactors safer.
+- MIT license, zero per-user costs.
+
+## Documentation and examples
+
+- [docs/quickstart.md](docs/quickstart.md) for full walkthrough
+- [examples/auth](examples/auth) for a runnable app
+
+## Contributing
+
+MIT licensed. Issues and PRs welcome.

belgie-0.1.0/pyproject.toml

@@ -0,0 +1,138 @@
+[project]
+name = "belgie"
+version = "0.1.0"
+description = "Modern authentication for FastAPI"
+readme = "README.md"
+authors = [
+    { name = "Matt LeMay", email = "mplemay@users.noreply.github.com" }
+]
+requires-python = ">=3.12,<3.15"
+dependencies = [
+    "belgie-proto",
+    "fastapi>=0.100",
+    "httpx>=0.24",
+    "pydantic>=2.0",
+    "pydantic-settings>=2.0",
+    "python-multipart>=0.0.20",
+]
+
+[project.optional-dependencies]
+alchemy = [
+    "belgie-alchemy",
+]
+all = [
+    "belgie-alchemy",
+    "belgie-mcp",
+    "belgie-oauth",
+]
+examples = [
+    "uvicorn[standard]>=0.38.0",
+]
+mcp = [
+    "belgie-mcp",
+]
+oauth = [
+    "belgie-oauth",
+]
+
+[build-system]
+requires = ["uv_build>=0.9.10,<0.10.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "aiosqlite>=0.21.0",
+    "belgie-alchemy",
+    "pre-commit>=4.4.0",
+    "pytest>=9.0.1",
+    "pytest-asyncio>=1.3.0",
+    "pytest-cov>=7.0.0",
+    "respx>=0.22.0",
+    "ruff>=0.14.5",
+    "rumdl",
+    "ty>=0.0.1a27",
+]
+
+[tool.uv.sources]
+belgie-alchemy = { workspace = true }
+belgie-mcp = { workspace = true }
+belgie-oauth = { workspace = true }
+belgie-proto = { workspace = true }
+
+[tool.uv.workspace]
+members = [
+    "packages/belgie-alchemy",
+    "packages/belgie-mcp",
+    "packages/belgie-oauth",
+    "packages/belgie-proto",
+]
+
+[tool.ruff]
+target-version = "py312"
+line-length = 120
+include = ["pyproject.toml"]
+
+[tool.ruff.lint]
+select = ["ALL"]
+ignore = [
+    "D", # pydocstyle (i.e. ignore missing/malformed docstrings)
+]
+
+[tool.ruff.lint.per-file-ignores]
+"__init__.py" = [
+    "F401", # imported but unused (common in __init__.py to re-export symbols)
+]
+"**/tests/**/*" = [
+    "ANN001",  # missing type annotation for function argument
+    "ANN201",  # missing return type annotation for public function
+    "ANN202",  # missing return type annotation for private function
+    "B008",    # function call in argument defaults (required for FastAPI Depends)
+    "F841",    # local variable assigned but never used
+    "FAST002", # FastAPI dependency without Annotated
+    "INP001",  # implicit namespace package (tests dir may not need __init__.py)
+    "PLR0913", # too many arguments in function definition
+    "PLR2004", # magic value used in comparison (fine in test cases)
+    "S101",    # use of assert (tests typically use assert directly)
+    "S106",    # possible hardcoded password (test secrets are fine)
+    "SLF001",  # private member accessed
+]
+"**/__tests__/**/*" = [
+    "ANN001",  # missing type annotation for function argument
+    "ANN201",  # missing return type annotation for public function
+    "ANN202",  # missing return type annotation for private function
+    "B008",    # function call in argument defaults (required for FastAPI Depends)
+    "F841",    # local variable assigned but never used
+    "FAST002", # FastAPI dependency without Annotated
+    "INP001",  # implicit namespace package (tests dir may not need __init__.py)
+    "PLR0913", # too many arguments in function definition
+    "PLR2004", # magic value used in comparison (fine in test cases)
+    "S101",    # use of assert (tests typically use assert directly)
+    "S106",    # possible hardcoded password (test secrets are fine)
+    "SLF001",  # private member accessed
+]
+
+[tool.ruff.lint.flake8-quotes]
+inline-quotes = "double"
+multiline-quotes = "double"
+
+[tool.ruff.lint.isort]
+combine-as-imports = true
+
+[tool.ruff.format]
+docstring-code-format = true
+quote-style = "double"
+
+[tool.pytest.ini_options]
+asyncio_mode = "strict"
+markers = [
+    "integration: marks tests that hit the database or external services",
+]
+filterwarnings = [
+    "error",
+]
+
+[tool.rumdl.MD013]
+line_length = 120
+reflow = true
+code_blocks = false
+tables = false

belgie-0.1.0/src/belgie/__init__.py

@@ -0,0 +1,97 @@
+"""Belgie - Modern authentication and analytics for FastAPI."""
+
+from importlib import import_module
+from typing import TYPE_CHECKING
+
+from belgie.auth import (
+    Auth,
+    AuthClient,
+    AuthenticationError,
+    AuthorizationError,
+    AuthSettings,
+    BelgieError,
+    ConfigurationError,
+    CookieSettings,
+    DBConnection,
+    GoogleOAuthProvider,
+    GoogleProviderSettings,
+    GoogleUserInfo,
+    HookContext,
+    HookEvent,
+    HookRunner,
+    Hooks,
+    InvalidStateError,
+    OAuthError,
+    OAuthProviderProtocol,
+    Providers,
+    SessionExpiredError,
+    SessionManager,
+    SessionSettings,
+    URLSettings,
+    generate_session_id,
+    generate_state_token,
+    parse_scopes,
+    validate_scopes,
+)
+
+if TYPE_CHECKING:
+    from belgie_alchemy import AlchemyAdapter as AlchemyAdapter
+
+__version__ = "0.1.0"
+
+_ALCHEMY_IMPORT_ERROR = "AlchemyAdapter requires the 'alchemy' extra. Install with: uv add belgie[alchemy]"
+
+
+def __getattr__(name: str) -> object:
+    if name != "AlchemyAdapter":
+        msg = f"module 'belgie' has no attribute {name!r}"
+        raise AttributeError(msg)
+
+    try:
+        module = import_module("belgie_alchemy")
+    except ModuleNotFoundError as exc:
+        raise ImportError(_ALCHEMY_IMPORT_ERROR) from exc
+
+    return module.AlchemyAdapter
+
+
+__all__ = [  # noqa: RUF022
+    # Version
+    "__version__",
+    # Core
+    "Auth",
+    "AuthClient",
+    "AuthSettings",
+    "Hooks",
+    "HookContext",
+    "HookEvent",
+    "HookRunner",
+    # Adapters
+    "AlchemyAdapter",
+    "DBConnection",
+    # Session
+    "SessionManager",
+    # Providers
+    "GoogleOAuthProvider",
+    "GoogleProviderSettings",
+    "GoogleUserInfo",
+    "OAuthProviderProtocol",
+    "Providers",
+    # Settings
+    "SessionSettings",
+    "CookieSettings",
+    "URLSettings",
+    # Exceptions
+    "BelgieError",
+    "AuthenticationError",
+    "AuthorizationError",
+    "SessionExpiredError",
+    "InvalidStateError",
+    "OAuthError",
+    "ConfigurationError",
+    # Utils
+    "generate_session_id",
+    "generate_state_token",
+    "parse_scopes",
+    "validate_scopes",
+]

belgie-0.1.0/src/belgie/alchemy.py

@@ -0,0 +1,24 @@
+"""Alchemy re-exports for belgie consumers."""
+
+_ALCHEMY_IMPORT_ERROR = "belgie.alchemy requires the 'alchemy' extra. Install with: uv add belgie[alchemy]"
+
+try:
+    from belgie_alchemy import (  # type: ignore[import-not-found]
+        AlchemyAdapter,
+        Base,
+        DatabaseSettings,
+        DateTimeUTC,
+        PrimaryKeyMixin,
+        TimestampMixin,
+    )
+except ModuleNotFoundError as exc:
+    raise ImportError(_ALCHEMY_IMPORT_ERROR) from exc
+
+__all__ = [
+    "AlchemyAdapter",
+    "Base",
+    "DatabaseSettings",
+    "DateTimeUTC",
+    "PrimaryKeyMixin",
+    "TimestampMixin",
+]