Metadata-Version: 2.4
Name: sreekarnv-fastauth
Version: 0.5.8
Summary: Deprecated FastAPI authentication package retained for existing users.
Project-URL: Homepage, https://github.com/sreekarnv/fastauth
Project-URL: Repository, https://github.com/sreekarnv/fastauth
Project-URL: Documentation, https://sreekarnv.github.io/fastauth/
Project-URL: Bug Tracker, https://github.com/sreekarnv/fastauth/issues
Project-URL: Changelog, https://github.com/sreekarnv/fastauth/blob/main/CHANGELOG.md
Author-email: Sreekar Nutulapati <sreekarnv1@gmail.com>
License: MIT
License-File: LICENSE
Classifier: Development Status :: 7 - Inactive
Classifier: Framework :: FastAPI
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Internet :: WWW/HTTP :: Session
Classifier: Topic :: Security
Requires-Python: >=3.11
Requires-Dist: cuid2>=2.0.1
Requires-Dist: pydantic[email]>=2.12.5
Provides-Extra: all
Requires-Dist: aiosmtplib>=5.1.0; extra == 'all'
Requires-Dist: aiosqlite>=0.22.1; extra == 'all'
Requires-Dist: argon2-cffi>=25.1.0; extra == 'all'
Requires-Dist: cryptography>=46.0.5; extra == 'all'
Requires-Dist: fastapi>=0.129.0; extra == 'all'
Requires-Dist: httpx>=0.28.1; extra == 'all'
Requires-Dist: jinja2>=3.1.6; extra == 'all'
Requires-Dist: joserfc>=1.6.1; extra == 'all'
Requires-Dist: redis>=7.1.1; extra == 'all'
Requires-Dist: rich>=13.0.0; extra == 'all'
Requires-Dist: sqlalchemy[asyncio]>=2.0.46; extra == 'all'
Requires-Dist: typer>=0.9.0; extra == 'all'
Requires-Dist: uvicorn>=0.40.0; extra == 'all'
Requires-Dist: webauthn>=2.7.1; extra == 'all'
Provides-Extra: argon2
Requires-Dist: argon2-cffi>=25.1.0; extra == 'argon2'
Provides-Extra: cli
Requires-Dist: rich>=13.0.0; extra == 'cli'
Requires-Dist: typer>=0.9.0; extra == 'cli'
Provides-Extra: email
Requires-Dist: aiosmtplib>=5.1.0; extra == 'email'
Requires-Dist: jinja2>=3.1.6; extra == 'email'
Provides-Extra: fastapi
Requires-Dist: fastapi>=0.129.0; extra == 'fastapi'
Requires-Dist: uvicorn>=0.40.0; extra == 'fastapi'
Provides-Extra: jwt
Requires-Dist: cryptography>=46.0.5; extra == 'jwt'
Requires-Dist: joserfc>=1.6.1; extra == 'jwt'
Provides-Extra: oauth
Requires-Dist: httpx>=0.28.1; extra == 'oauth'
Provides-Extra: postgresql
Requires-Dist: asyncpg>=0.31.0; extra == 'postgresql'
Provides-Extra: redis
Requires-Dist: redis>=7.1.1; extra == 'redis'
Provides-Extra: sqlalchemy
Requires-Dist: aiosqlite>=0.22.1; extra == 'sqlalchemy'
Requires-Dist: sqlalchemy[asyncio]>=2.0.46; extra == 'sqlalchemy'
Provides-Extra: standard
Requires-Dist: aiosqlite>=0.22.1; extra == 'standard'
Requires-Dist: argon2-cffi>=25.1.0; extra == 'standard'
Requires-Dist: cryptography>=46.0.5; extra == 'standard'
Requires-Dist: fastapi>=0.129.0; extra == 'standard'
Requires-Dist: joserfc>=1.6.1; extra == 'standard'
Requires-Dist: sqlalchemy[asyncio]>=2.0.46; extra == 'standard'
Requires-Dist: uvicorn>=0.40.0; extra == 'standard'
Provides-Extra: webauthn
Requires-Dist: webauthn>=2.7.1; extra == 'webauthn'
Description-Content-Type: text/markdown

# FastAuth

> [!CAUTION]
>
> ## FastAuth is deprecated
>
> FastAuth is no longer actively maintained. It will not receive new features, compatibility updates, or security fixes, and it is not recommended for new projects.
>
> Development has moved to [AuthLoom](https://github.com/sreekarnv/authloom), a new authentication library built from scratch with a smaller and more focused scope.
>
> **AuthLoom is not a drop-in replacement for FastAuth.** Existing FastAuth applications should pin their current version and evaluate migration manually.
>
> This repository is retained for existing users and historical reference.

[![PyPI](https://img.shields.io/pypi/v/sreekarnv-fastauth)](https://pypi.org/project/sreekarnv-fastauth/)
[![Status: Deprecated](https://img.shields.io/badge/status-deprecated-red)](https://github.com/sreekarnv/fastauth)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue)](https://www.python.org/downloads/)

**Deprecated FastAPI authentication package retained for existing users and historical reference.**

FastAuth previously provided credentials authentication, OAuth, magic links, passkeys (WebAuthn), JWT access/refresh pairs, email flows, RBAC, JWKS support, adapters, and extension interfaces.

The remaining documentation describes the final FastAuth implementation and must not be interpreted as a recommendation for new projects.

## Project status

| | |
|---|---|
| **Status** | Deprecated |
| **Active development** | No |
| **Security updates** | No |
| **Recommended for new projects** | No |
| **Successor project** | [AuthLoom](https://github.com/sreekarnv/authloom) |
| **Drop-in replacement available** | No |

AuthLoom intentionally has a smaller scope and a different API and architecture.

---

## Features

- **Multiple providers** — email/password, magic links, Google OAuth, GitHub OAuth, passkeys (WebAuthn)
- **OAuth account linking** — connect additional providers to an existing account while authenticated
- **Pluggable adapters** — SQLAlchemy (SQLite, PostgreSQL, MySQL) or bring your own
- **JWT token pairs** — stateless access + refresh tokens, with optional `/auth/sessions` user-session tracking via `session_adapter`
- **Cookie delivery** — HttpOnly, Secure, SameSite out of the box
- **Email flows** — verification, password reset, and magic links with customizable transports
- **Custom email templates** — drop Jinja2 templates into any directory; unoverridden templates fall back to built-ins
- **RBAC** — roles and fine-grained permissions on any route
- **Event hooks** — intercept sign-in/sign-up and modify JWT payloads
- **RS256 / JWKS** — rotate keys and expose a JWKS endpoint for microservices
- **CLI** — scaffold a project, check dependencies, generate secrets

---

## Install

> [!WARNING]
> FastAuth is deprecated and should not be installed for new projects.
> These installation instructions are retained for applications that already
> depend on FastAuth.

Existing users should pin the exact FastAuth version they currently use.

```bash
pip install "sreekarnv-fastauth[standard]"
```

| Extra | Includes |
|-------|----------|
| `standard` | FastAPI, JWT (joserfc), SQLAlchemy, Argon2 |
| `oauth` | httpx (Google, GitHub OAuth) |
| `webauthn` | py-webauthn (passkeys / FIDO2) |
| `email` | aiosmtplib, Jinja2 |
| `redis` | redis-py async |
| `postgresql` | asyncpg |
| `cli` | typer, rich |
| `all` | everything |

---

## Quick start

```python
from contextlib import asynccontextmanager
from fastapi import Depends, FastAPI
from fastauth import FastAuth, FastAuthConfig
from fastauth.adapters.sqlalchemy import SQLAlchemyAdapter
from fastauth.api.deps import require_auth
from fastauth.providers.credentials import CredentialsProvider

adapter = SQLAlchemyAdapter(engine_url="sqlite+aiosqlite:///./auth.db")

auth = FastAuth(FastAuthConfig(
    secret="change-me-in-production-min-32-bytes!!",           # fastauth generate-secret
    providers=[CredentialsProvider()],
    adapter=adapter.user,
    token_adapter=adapter.token,
))

@asynccontextmanager
async def lifespan(app: FastAPI):
    await adapter.create_tables()
    yield

app = FastAPI(lifespan=lifespan)
auth.mount(app)  # registers /auth/register, /auth/login, /auth/logout, …

@app.get("/dashboard")
async def dashboard(user=Depends(require_auth)):
    return {"hello": user["email"]}
```

```bash
uvicorn main:app --reload
```

---

## Magic Links

Passwordless sign-in with a one-time link sent to the user's email. No password required — unknown emails are auto-registered on first use.

```python
from fastauth.providers.magic_links import MagicLinksProvider
from fastauth.email_transports.smtp import SMTPTransport

auth = FastAuth(FastAuthConfig(
    ...
    providers=[MagicLinksProvider()],
    token_adapter=adapter.token,
    email_transport=SMTPTransport(...),
    base_url="https://your-app.com",
))
```

```bash
pip install "sreekarnv-fastauth[standard,email]"
```

See the [Magic Links guide](https://sreekarnv.github.io/fastauth/guides/magic-links/) and [example app](https://github.com/sreekarnv/fastauth/tree/main/examples/magic_link).

---

## Passkeys (WebAuthn)

Add Touch ID, Face ID, and Windows Hello sign-in with one extra import:

```python
from fastauth.providers.passkey import PasskeyProvider
from fastauth.session_backends.memory import MemorySessionBackend

auth = FastAuth(FastAuthConfig(
    ...
    providers=[
        CredentialsProvider(),
        PasskeyProvider(rp_id="example.com", rp_name="My App", origin="https://example.com"),
    ],
    passkey_adapter=adapter.passkey,
    passkey_state_store=MemorySessionBackend(),
))
```

```bash
pip install "sreekarnv-fastauth[standard,webauthn]"
```

See the [Passkeys guide](https://sreekarnv.github.io/fastauth/guides/passkeys/) and [example app](https://github.com/sreekarnv/fastauth/tree/main/examples/passkeys).

---

## OAuth Account Linking

Authenticated users can connect additional OAuth providers to their existing account — no new sign-in flow required.

```python
# 1. Get the authorization URL (requires Bearer token)
GET /auth/oauth/google/link?redirect_uri=https://your-app.com/callback

# → {"url": "https://accounts.google.com/o/oauth2/auth?..."}

# 2. After the provider redirects back, the callback completes the link
GET /auth/oauth/google/link/callback?code=...&state=...

# → {"message": "Google account linked successfully"}

# 3. List all linked providers
GET /auth/oauth/accounts
```

Requires `oauth_state_store` and `oauth_adapter` in `FastAuthConfig`. Attempting to link an already-linked provider account returns `400`.

---

## Custom Email Templates

Drop Jinja2 templates into any directory to override FastAuth's built-in emails. Only the files you provide are replaced — everything else falls back to the defaults automatically.

```python
from pathlib import Path

auth = FastAuth(FastAuthConfig(
    ...
    email_template_dir=Path("my_templates/"),
))
```

| Template file | Sent when | Variables |
|---|---|---|
| `welcome.jinja2` | User registers | `name` |
| `verification.jinja2` | Email verification | `name`, `url`, `expires_in_minutes` |
| `password_reset.jinja2` | Password reset | `name`, `url`, `expires_in_minutes` |
| `email_change.jinja2` | Email change | `name`, `new_email`, `url`, `expires_in_minutes` |
| `magic_link_login.jinja2` | Magic link sign-in | `name`, `url` |

See the [example app](https://github.com/sreekarnv/fastauth/tree/main/examples/custom_templates).

---

## Historical documentation

These docs cover the final FastAuth implementation and are retained for existing users and historical reference: **[sreekarnv.github.io/fastauth](https://sreekarnv.github.io/fastauth)**

- [Installation](https://sreekarnv.github.io/fastauth/getting-started/installation/)
- [Quick Start](https://sreekarnv.github.io/fastauth/getting-started/quick-start/)
- [Configuration](https://sreekarnv.github.io/fastauth/getting-started/configuration/)
- [Architecture](https://sreekarnv.github.io/fastauth/concepts/architecture/)
- [Magic Links](https://sreekarnv.github.io/fastauth/features/magic-links/)
- [Passkeys (WebAuthn)](https://sreekarnv.github.io/fastauth/features/passkeys/)
- [Guides](https://sreekarnv.github.io/fastauth/guides/basic/)
- [API Reference](https://sreekarnv.github.io/fastauth/reference/fastauth/)

---

## Maintenance and contributions

FastAuth is deprecated and is no longer accepting feature requests or contributions.

Existing issues, pull requests, documentation, and source code are retained for historical reference. Users maintaining an existing FastAuth application should pin the exact package version they currently use.

For new development, see [AuthLoom](https://github.com/sreekarnv/authloom). AuthLoom is a separate implementation and does not provide an automatic migration path from FastAuth.

---

## License

MIT License - see [LICENSE](./LICENSE) for details.
