belgie 0.1.0a4__py3-none-any.whl

belgie-0.1.0a4.dist-info/METADATA

@@ -0,0 +1,231 @@
+Metadata-Version: 2.3
+Name: belgie
+Version: 0.1.0a4
+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.0a4.dist-info/RECORD

@@ -0,0 +1,24 @@
+belgie/__init__.py,sha256=LnGyYbGGkEt0UAb_Y-gHRcRSFECPNsTFca7xTZttPmM,2093
+belgie/alchemy.py,sha256=8EywiqMMDYkLQ0WvnnxEKaVo2BQhAqq6R0NyIFkA9dI,595
+belgie/auth/__init__.py,sha256=NPl9oQBF8TVLxFEz6tzdCBf2eHbLtpDevoDz8H14zsA,1680
+belgie/auth/core/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+belgie/auth/core/auth.py,sha256=CnkT6SSAjt2J-dAL2ye8-1aiILSM-tVPRXbReihVbwA,13335
+belgie/auth/core/client.py,sha256=foNqGInCuWM-neSCc63bsGePTd8IB-RxM1gMDpui26c,7102
+belgie/auth/core/exceptions.py,sha256=KF_pBbw-KJcrn5S6qCTa55YMcwRLETc5vEwXl4EmGwk,340
+belgie/auth/core/hooks.py,sha256=mjksSE5YxjD-0WIn_mGIOl6DA_3socxoN1IpIrzo6uU,2993
+belgie/auth/core/settings.py,sha256=SN-ChAVFSpgyBbWtTrdpNkBamjY1XjnbxqHCp5Mjg8U,3258
+belgie/auth/providers/__init__.py,sha256=N0E7Kv_-Hc7PE0C-S2cS5uQDt9BXxRJHbYToUlipniE,318
+belgie/auth/providers/google.py,sha256=MfHBcXlbyOKBP97fZPiSj76ct53sToXdqZbXcZAv6Aw,11411
+belgie/auth/providers/protocols.py,sha256=1EeBmRDDbiYkITDE-EMNlddp-fUjkkq1NV1Nz0BUPlg,1312
+belgie/auth/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+belgie/auth/session/__init__.py,sha256=p7DWWy_TMMWYgg-ltZn8lFJgHJXi_yPWhgjE54i7ptk,85
+belgie/auth/session/manager.py,sha256=XLUyihJTpvcRmsPa2Nidc2GuxyNB7cVhHqPABuZvcXM,5353
+belgie/auth/utils/__init__.py,sha256=VqaeGLT2v-giVLOXOWAJ8gFu89IqMiknXXHpBKIUijU,259
+belgie/auth/utils/crypto.py,sha256=mtV3HNIWu1hDw7JaKqUWMdWi6_x2crEY5sg49AoUL3U,174
+belgie/auth/utils/scopes.py,sha256=OIdI039U7uB9w7Y91QNuY05PBSrtcZz0ruqIY0Fvyik,1598
+belgie/mcp.py,sha256=FS3K9jE883yH8pA4agkvI5r_WukJCI2X4j1utwJs48A,322
+belgie/oauth.py,sha256=ArGIJUnAlPz3Xa4Tiyzo0nYUC9Vuv7R2XEGxgfS-Uuc,336
+belgie/proto.py,sha256=gRSvV5DGulNFFzPnC983jEKlbj7oUdG9Gk259qJ_rqE,562
+belgie-0.1.0a4.dist-info/WHEEL,sha256=fAguSjoiATBe7TNBkJwOjyL1Tt4wwiaQGtNtjRPNMQA,80
+belgie-0.1.0a4.dist-info/METADATA,sha256=dD2y0UNM05GVCrdYBgleM00VtMnZ45LWOgSsLQrdCiU,7971
+belgie-0.1.0a4.dist-info/RECORD,,

belgie-0.1.0a4.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: uv 0.9.28
+Root-Is-Purelib: true
+Tag: py3-none-any