ironauth 0.1.0__tar.gz

ironauth-0.1.0/.gitignore

@@ -0,0 +1,52 @@
+# Python
+__pycache__/
+*.py[cod]
+*.pyo
+*.pyd
+*.so
+*.egg
+*.egg-info/
+dist/
+build/
+eggs/
+parts/
+var/
+sdist/
+develop-eggs/
+.installed.cfg
+lib/
+lib64/
+
+# uv
+.venv/
+.python-version
+uv.lock
+
+# Tests
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+
+# MkDocs
+site/
+
+# Env
+.env
+.env.local
+.env.*.local
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Secrets
+*.pem
+*.key
+.pypirc

ironauth-0.1.0/PKG-INFO

@@ -0,0 +1,25 @@
+Metadata-Version: 2.4
+Name: ironauth
+Version: 0.1.0
+Summary: Framework-agnostic authentication library for Python
+Project-URL: Homepage, https://github.com/sileyekounou-1/ironauth
+Project-URL: Repository, https://github.com/sileyekounou-1/ironauth
+Author-email: sileyekounou-1 <kounousileye@gmail.com>
+License: MIT
+Keywords: auth,authentication,fastapi,jwt,oauth
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: FastAPI
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Security
+Requires-Python: >=3.11
+Requires-Dist: fastapi>=0.136.1
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: passlib[argon2]>=1.7.4
+Requires-Dist: pydantic[email]>=2.13.4
+Requires-Dist: pyjwt>=2.12.1
+Requires-Dist: pyotp>=2.9.0
+Requires-Dist: qrcode[pil]>=8.2
+Requires-Dist: sqlalchemy>=2.0.49

ironauth-0.1.0/docs/api-references.md

@@ -0,0 +1,54 @@
+# API Reference
+
+## ironauth
+
+```python
+ironauth(
+    database: SQLAlchemyAdapter,
+    config: dict,
+    plugins: list = [],
+    adapter: dict | None = None,
+)
+```
+
+| Parameter  | Type                | Description                                                |
+| ---------- | ------------------- | ---------------------------------------------------------- |
+| `database` | `SQLAlchemyAdapter` | Database adapter                                           |
+| `config`   | `dict`              | Configuration dict (see [Configuration](configuration.md)) |
+| `plugins`  | `list`              | List of plugins                                            |
+| `adapter`  | `dict`              | Framework adapter                                          |
+
+### Methods
+
+| Method                             | Description                |
+| ---------------------------------- | -------------------------- |
+| `await auth.init()`                | Initialize database tables |
+| `auth.router`                      | FastAPI router to mount    |
+| `auth.current_user(required=True)` | FastAPI dependency         |
+
+## Routes
+
+### Email / Password
+
+| Method | Route            | Body                | Description     |
+| ------ | ---------------- | ------------------- | --------------- |
+| `POST` | `/auth/register` | `{email, password}` | Register        |
+| `POST` | `/auth/login`    | `{email, password}` | Login           |
+| `POST` | `/auth/logout`   | —                   | Logout          |
+| `POST` | `/auth/refresh`  | —                   | Refresh session |
+
+### OAuth
+
+| Method | Route                             | Description      |
+| ------ | --------------------------------- | ---------------- |
+| `GET`  | `/auth/oauth/{provider}`          | Start OAuth flow |
+| `GET`  | `/auth/oauth/{provider}/callback` | OAuth callback   |
+
+### 2FA
+
+| Method | Route                | Body              | Description      |
+| ------ | -------------------- | ----------------- | ---------------- |
+| `POST` | `/auth/2fa/enable`   | —                 | Generate QR code |
+| `POST` | `/auth/2fa/confirm`  | `{code}`          | Activate 2FA     |
+| `POST` | `/auth/2fa/validate` | `{user_id, code}` | Validate code    |
+| `POST` | `/auth/2fa/disable`  | `{code}`          | Disable 2FA      |

ironauth-0.1.0/docs/configuration.md

@@ -0,0 +1,65 @@
+# Configuration
+
+## Full reference
+
+```python
+auth = ironauth(
+    database=sqlalchemy_adapter("postgresql+asyncpg://..."),
+    adapter=fastapi_adapter(),
+    plugins=[...],
+    config={
+        # Required
+        "secret_key": "your-secret-key",
+
+        # Token settings (optional)
+        "token": {
+            "access_token_expiry": 900,       # 15 minutes
+            "refresh_token_expiry": 604800,   # 7 days
+            "algorithm": "HS256",
+        },
+
+        # Cookie settings (optional)
+        "cookie": {
+            "http_only": True,
+            "secure": True,
+            "same_site": "lax",
+            "access_token_name": "af_access_token",
+            "refresh_token_name": "af_refresh_token",
+        },
+
+        # OAuth (required if using oauth plugin)
+        "oauth": {
+            "google": {
+                "client_id": "...",
+                "client_secret": "...",
+                "redirect_uri": "http://localhost:8000/auth/oauth/google/callback",
+            },
+            "github": {
+                "client_id": "...",
+                "client_secret": "...",
+                "redirect_uri": "http://localhost:8000/auth/oauth/github/callback",
+            },
+        },
+    },
+)
+```
+
+## Security defaults
+
+ironauth ships with secure defaults out of the box.
+
+| Setting                | Default | Why                                    |
+| ---------------------- | ------- | -------------------------------------- |
+| Password hashing       | Argon2  | Winner of Password Hashing Competition |
+| Cookie `HttpOnly`      | `True`  | Prevents XSS token theft               |
+| Cookie `Secure`        | `True`  | HTTPS only                             |
+| Cookie `SameSite`      | `lax`   | CSRF protection                        |
+| Access token expiry    | 15 min  | Limits exposure window                 |
+| Refresh token rotation | Always  | Detects token theft                    |
+
+!!! warning "Secret key"
+Always use a long random secret key in production.
+
+```bash
+    python -c "import secrets; print(secrets.token_urlsafe(64))"
+```

ironauth-0.1.0/docs/getting-started.md

@@ -0,0 +1,71 @@
+# Getting Started
+
+## Installation
+
+```bash
+pip install ironauth
+
+# With uv
+uv add ironauth
+```
+
+## Minimal setup
+
+### 1. Create your ironauth instance
+
+```python
+# auth.py
+from ironauth import ironauth
+from ironauth.adapters.database.sqlalchemy import sqlalchemy_adapter
+from ironauth.adapters.frameworks.fastapi import fastapi_adapter
+
+auth = ironauth(
+    database=sqlalchemy_adapter("sqlite+aiosqlite:///./db.sqlite3"),
+    adapter=fastapi_adapter(),
+    config={"secret_key": "change-me-in-production"},
+)
+```
+
+### 2. Mount on your FastAPI app
+
+```python
+# main.py
+from fastapi import FastAPI, Depends
+from auth import auth
+
+app = FastAPI()
+
+@app.on_event("startup")
+async def startup():
+    await auth.init()  # Creates tables automatically
+
+app.include_router(auth.router)
+```
+
+### 3. Protect a route
+
+```python
+@app.get("/profile")
+async def profile(user=Depends(auth.current_user())):
+    return {"email": user.email}
+```
+
+That's it. You now have the following routes available:
+
+| Method | Route            | Description                    |
+| ------ | ---------------- | ------------------------------ |
+| `POST` | `/auth/register` | Register with email + password |
+| `POST` | `/auth/login`    | Login                          |
+| `POST` | `/auth/logout`   | Logout                         |
+| `POST` | `/auth/refresh`  | Refresh session                |
+
+## Optional routes
+
+```python
+# Unprotected route (user may or may not be logged in)
+@app.get("/public")
+async def public(user=Depends(auth.current_user(required=False))):
+    if user:
+        return {"message": f"Hello {user.email}"}
+    return {"message": "Hello stranger"}
+```

ironauth-0.1.0/docs/guides/oauth.md

@@ -0,0 +1,46 @@
+# OAuth
+
+ironauth supports OAuth2 with Google and GitHub out of the box.
+
+## Setup
+
+### 1. Get your credentials
+
+=== "Google" 1. Go to [Google Cloud Console](https://console.cloud.google.com) 2. Create a project → APIs & Services → Credentials 3. Create OAuth 2.0 Client ID 4. Add `http://localhost:8000/auth/oauth/google/callback` to authorized redirect URIs
+
+=== "GitHub" 1. Go to GitHub → Settings → Developer settings → OAuth Apps 2. Create a new OAuth App 3. Set callback URL to `http://localhost:8000/auth/oauth/github/callback`
+
+### 2. Configure ironauth
+
+```python
+from ironauth.plugins.oauth import oauth
+
+auth = ironauth(
+    ...
+    plugins=[oauth(providers=["google", "github"])],
+    config={
+        "secret_key": "...",
+        "oauth": {
+            "google": {
+                "client_id": "YOUR_CLIENT_ID",
+                "client_secret": "YOUR_CLIENT_SECRET",
+                "redirect_uri": "http://localhost:8000/auth/oauth/google/callback",
+            },
+        },
+    },
+)
+```
+
+### 3. Redirect your users
+
+```python
+# Frontend: redirect to this URL to start OAuth flow
+GET /auth/oauth/google
+GET /auth/oauth/github
+```
+
+ironauth handles the callback automatically and sets session cookies.
+
+## Account linking
+
+If a user signs in with OAuth using an email that already exists in your database, ironauth automatically links the OAuth account to the existing user — no duplicate accounts.

ironauth-0.1.0/docs/guides/two-factor.md

@@ -0,0 +1,56 @@
+# Two-Factor Authentication (TOTP)
+
+ironauth supports TOTP-based 2FA compatible with Google Authenticator, Authy, and any TOTP app.
+
+## Setup
+
+```python
+from ironauth.plugins.two_factor import two_factor
+
+auth = ironauth(
+    ...
+    plugins=[two_factor()],
+)
+```
+
+## Flow
+
+### Enable 2FA
+
+```python
+# 1. Request setup — returns QR code + secret
+POST /auth/2fa/enable
+# Response:
+{
+    "secret": "BASE32SECRET",
+    "qr_code": "<base64 PNG>"
+}
+```
+
+Display the QR code to your user so they can scan it with their TOTP app.
+
+```python
+# 2. Confirm with first code
+POST /auth/2fa/confirm
+{ "code": "123456" }
+```
+
+### Validate at login
+
+```python
+POST /auth/2fa/validate
+{
+    "user_id": "...",
+    "code": "123456"
+}
+```
+
+### Disable 2FA
+
+```python
+POST /auth/2fa/disable
+{ "code": "123456" }
+```
+
+!!! info "TOTP window"
+ironauth accepts codes valid within a 30-second window before and after the current time to account for clock drift.

ironauth-0.1.0/docs/index.md

@@ -0,0 +1,41 @@
+# ironauth
+
+**ironauth** is a framework-agnostic authentication library for Python — simple to use, secure by default, and extensible via plugins.
+
+## Why ironauth?
+
+The Python ecosystem has authentication solutions, but none that feel like a single cohesive tool across frameworks. ironauth changes that.
+
+- **Framework-agnostic** — FastAPI today, Django and Flask coming soon
+- **Secure by default** — Argon2 hashing, HTTP-only cookies, JWT rotation
+- **Plugin system** — OAuth, 2FA, and more
+- **Fully async** — built for modern Python
+
+## Quick example
+
+```python
+from ironauth import ironauth
+from ironauth.adapters.database import sqlalchemy_adapter
+from ironauth.adapters.frameworks import fastapi_adapter
+from ironauth.plugins import oauth, two_factor
+
+auth = ironauth(
+    database=sqlalchemy_adapter("postgresql+asyncpg://user:pass@localhost/db"),
+    adapter=fastapi_adapter(),
+    plugins=[
+        oauth(providers=["google", "github"]),
+        two_factor(),
+    ],
+    config={"secret_key": "your-secret-key"},
+)
+
+app.include_router(auth.router)
+```
+
+## Installation
+
+```bash
+pip install ironauth
+```
+
+[Get started →](getting-started.md)

ironauth-0.1.0/ironauth/adapters/database/sqlalchemy.py

@@ -0,0 +1,91 @@
+from typing import Any, Optional
+
+from ironauth.models.user import Base, OAuthAccount, User
+from sqlalchemy import delete, select, update
+from sqlalchemy.ext.asyncio import async_sessionmaker, create_async_engine
+
+
+class SQLAlchemyAdapter:
+    def __init__(self, database_url: str):
+        self.engine = create_async_engine(database_url, echo=False)
+        self.session_factory = async_sessionmaker(self.engine, expire_on_commit=False)
+
+    async def init(self):
+        async with self.engine.begin() as conn:
+            await conn.run_sync(Base.metadata.create_all)
+
+    # --- User ---
+
+    async def create_user(
+        self, email: str, hashed_password: Optional[str] = None
+    ) -> User:
+        async with self.session_factory() as session:
+            user = User(email=email, hashed_password=hashed_password)
+            session.add(user)
+            await session.commit()
+            await session.refresh(user)
+            return user
+
+    async def get_user_by_email(self, email: str) -> Optional[User]:
+        async with self.session_factory() as session:
+            result = await session.execute(select(User).where(User.email == email))
+            return result.scalar_one_or_none()
+
+    async def get_user_by_id(self, user_id: str) -> Optional[User]:
+        async with self.session_factory() as session:
+            result = await session.execute(select(User).where(User.id == user_id))
+            return result.scalar_one_or_none()
+
+    async def update_user(self, user_id: str, **kwargs: Any) -> Optional[User]:
+        async with self.session_factory() as session:
+            await session.execute(
+                update(User).where(User.id == user_id).values(**kwargs)
+            )
+            await session.commit()
+            return await self.get_user_by_id(user_id)
+
+    async def delete_user(self, user_id: str) -> None:
+        async with self.session_factory() as session:
+            await session.execute(delete(User).where(User.id == user_id))
+            await session.commit()
+
+    # --- OAuth ---
+
+    async def create_oauth_account(
+        self,
+        user_id: str,
+        provider: str,
+        provider_user_id: str,
+        access_token: str,
+        refresh_token: Optional[str] = None,
+        expires_at=None,
+    ) -> OAuthAccount:
+        async with self.session_factory() as session:
+            account = OAuthAccount(
+                user_id=user_id,
+                provider=provider,
+                provider_user_id=provider_user_id,
+                access_token=access_token,
+                refresh_token=refresh_token,
+                expires_at=expires_at,
+            )
+            session.add(account)
+            await session.commit()
+            await session.refresh(account)
+            return account
+
+    async def get_oauth_account(
+        self, provider: str, provider_user_id: str
+    ) -> Optional[OAuthAccount]:
+        async with self.session_factory() as session:
+            result = await session.execute(
+                select(OAuthAccount).where(
+                    OAuthAccount.provider == provider,
+                    OAuthAccount.provider_user_id == provider_user_id,
+                )
+            )
+            return result.scalar_one_or_none()
+
+
+def sqlalchemy_adapter(database_url: str) -> SQLAlchemyAdapter:
+    return SQLAlchemyAdapter(database_url)