Metadata-Version: 2.5
Name: fastapi_myauth
Version: 1.6.0
Summary: A flexible and secure authentication library for FastAPI.
License: MIT
License-File: LICENSE
Requires-Python: >=3.13
Requires-Dist: cryptography>=50.0.0
Requires-Dist: email-validator<3.0.0.0,>=2.3.0
Requires-Dist: emails==0.6.0
Requires-Dist: fastapi==0.143.*
Requires-Dist: jinja2<4.0.0,>=3.1.6
Requires-Dist: pwdlib[argon2,bcrypt]>=0.3.0
Requires-Dist: pyjwt>=2.15.0
Requires-Dist: pyotp>=2.8.0
Requires-Dist: python-multipart<1.0.0,>=0.0.32
Requires-Dist: sqlmodel==0.0.48
Provides-Extra: passkeys
Requires-Dist: webauthn<4,>=3.0; extra == 'passkeys'
Provides-Extra: redis
Requires-Dist: redis<8.0.0,>=5.0.0; extra == 'redis'
Provides-Extra: social
Requires-Dist: authlib<2.0.0,>=1.7.2; extra == 'social'
Requires-Dist: httpx<1.0.0,>=0.28.1; extra == 'social'
Requires-Dist: itsdangerous<3.0.0,>=2.2.0; extra == 'social'
Description-Content-Type: text/markdown

# FastAPI MyAuth

Authentication and user management for FastAPI applications using synchronous
SQLModel sessions. Requires Python 3.13 or newer.

The package provides email/password and magic-link login, rotating refresh
tokens, email confirmation, password recovery, TOTP, role checks, and optional
OIDC providers, WebAuthn passkeys, and application rate limiting.

```bash
pip install fastapi_myauth
# Optional features, independently installable:
pip install 'fastapi_myauth[social,passkeys,redis]'
```

## Quick start

Save this as `main.py`. Generate and persist two separate secrets before starting
it (see [Configuration](docs/usage/CONFIGURATION.md)). The example disables email
confirmation for local use; configure SMTP to enable email flows.

```python
from contextlib import asynccontextmanager
import os

from fastapi import Depends, FastAPI
from sqlmodel import SQLModel, create_engine

from fastapi_myauth import models
from fastapi_myauth.auth import AuthComponents, FastAuth
from fastapi_myauth.config import Settings

engine = create_engine("sqlite:///database.db", connect_args={"check_same_thread": False})
config = Settings(
    SECRET_KEY=os.environ["AUTH_SECRET_KEY"],
    TOTP_SECRET_KEY=os.environ["AUTH_TOTP_SECRET_KEY"],
    REQUIRE_EMAIL_VALIDATION=False,
)
components = AuthComponents(config=config)
fast_auth = FastAuth(engine=engine, components=components)


@asynccontextmanager
async def lifespan(_app: FastAPI):
    SQLModel.metadata.create_all(engine)
    yield


app = FastAPI(lifespan=lifespan)
app.include_router(fast_auth.get_router())


@app.get("/protected", response_model=models.UserRead)
def protected(current_user=Depends(fast_auth.deps.get_current_active_user)):
    return current_user
```

Install a server separately, then run `uvicorn main:app --reload`.
Sign up at `POST /login/signup` with an email and an 8–64 character password;
log in at `POST /login/oauth` with form fields `username` and `password`.
Send the returned access token as `Authorization: Bearer <token>`.
Interactive API documentation is available at `/docs`.

`config` belongs to `AuthComponents`; `FastAuth` receives the engine and
components. `fast_auth.deps` and `fast_auth.crud_user` are properties.
Custom user models must inherit from `models.User` **without `table=True`**:
`AuthComponents` creates the mapped table and relationships. Use
`fast_auth.User` for database queries.

## Documentation

- [Getting started](docs/usage/GETTING_STARTED.md)
- [Configuration and SMTP](docs/usage/CONFIGURATION.md)
- [Custom user models](docs/usage/CUSTOM_USER_MODELS.md)
- [API reference](docs/usage/API_REFERENCE.md)
- [Social login](docs/usage/SOCIAL_LOGIN.md)
- [Passkeys](docs/usage/PASSKEYS.md)
- [Rate limiting](docs/usage/RATE_LIMITING.md)
- [Sessions and account recovery](docs/usage/SESSIONS_AND_RECOVERY.md)
- [Development setup](docs/development/SETUP.md)
- [Contributing](docs/development/CONTRIBUTING.md)
- [Release procedure](docs/development/RELEASING.md)

## Repository layout

```text
fastapi_myauth/             Installable library
  api/endpoints/           Router factories
  api/deps.py              Authentication and session dependencies
  crud/                    Synchronous database operations
  models/                  API schemas and mapped models
  auth.py                  AuthComponents and FastAuth
  config.py                Explicit Pydantic settings
  security.py              Hashing, JWT and TOTP helpers
  services.py              Token issuance and one-time email challenges
  email.py                 SMTP delivery
  email-templates/         MJML sources and packaged HTML
examples/main.py           Local demo, initialized through lifespan
tests/                    Isolated in-memory SQLite integration tests
scripts/                  Coverage and distribution checks
docs/                     Development and usage guides
```

## Development

```bash
uv sync --locked --all-extras
make ci
```

CI checks lint and formatting, runs tests with branch coverage (minimum 90%),
and builds and inspects distributions. Tests never remove or reuse an
application's `database.db`.

## License

[MIT](LICENSE).
