Metadata-Version: 2.4
Name: aegistry
Version: 0.1.0
Summary: Batteries-included authentication toolkit for FastAPI — a friendly fork of reauth
Project-URL: Source, https://github.com/primemeridiem/aegistry
Author: aegistry
License: MIT License
        
        Copyright (c) 2026, François Voron
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
License-File: LICENSE
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Python: >=3.12
Requires-Dist: anyio
Requires-Dist: cryptography<49.0.0,>=48.0.0
Requires-Dist: httpx>=0.28.1
Requires-Dist: pyjwt>=2.12.1
Provides-Extra: all
Requires-Dist: email-validator>=2.0; extra == 'all'
Requires-Dist: fastapi>=0.115.0; extra == 'all'
Requires-Dist: pwdlib[argon2]>=0.2.1; extra == 'all'
Requires-Dist: sqlalchemy[asyncio]>=2.0.30; extra == 'all'
Provides-Extra: fastapi
Requires-Dist: email-validator>=2.0; extra == 'fastapi'
Requires-Dist: fastapi>=0.115.0; extra == 'fastapi'
Provides-Extra: password
Requires-Dist: pwdlib[argon2]>=0.2.1; extra == 'password'
Provides-Extra: sqlalchemy
Requires-Dist: sqlalchemy[asyncio]>=2.0.30; extra == 'sqlalchemy'
Description-Content-Type: text/markdown

# Aegistry

<p align="center">
    <em>Batteries-included authentication for FastAPI</em>
</p>

Aegistry is an authentication toolkit for Python with first-class FastAPI
integration: Email/Password, Email OTP, Google Sign-In, LINE Login, MFA
(TOTP, backup codes), and session management — on Python 3.12+.

> [!NOTE]
> Aegistry's core is a friendly fork of [reauth](https://github.com/frankie567/reauth)
> 0.1.8 (MIT, © 2026 François Voron), backported to Python 3.12. Aegistry adds the
> integration layers reauth doesn't ship yet: password & LINE factors, post-login
> session management, SQLAlchemy stores, and ready-made FastAPI routers. We aim to
> stay architecturally compatible with reauth and upstream what makes sense.

## Architecture

```
aegistry/
├── crypto.py                  # opaque tokens + HMAC-SHA256 hash pairs
├── amr.py                     # RFC 8176 Authentication Method References
├── authentication_session.py  # pre-login MFA state machine (steps, AMR)
├── session.py                 # post-login sessions (sliding expiration)
├── factors/
│   ├── password.py            # argon2id via pwdlib          [aegistry]
│   ├── email_otp.py           # one-time codes by email
│   ├── totp.py / hotp.py / backup_codes.py
│   └── oauth2/
│       ├── base.py            # OAuth2 authorization code + PKCE
│       ├── oidc.py            # discovery, JWKS, id_token validation
│       ├── google.py / github.py / apple.py
│       └── line.py            # LINE Login v2.1               [aegistry]
└── contrib/
    ├── sqlalchemy/            # ready-made async stores        [aegistry]
    └── fastapi/               # routers, dependencies, cookies [aegistry]

clients/                       # TypeScript SDK (pnpm workspace) [aegistry]
├── packages/client            # @aegistry/client — core, getServerSession
└── packages/react             # @aegistry/react — useSession()
```

For the Next.js/React side, see [clients/README.md](clients/README.md).

Design principles (inherited from reauth, shared with Better Auth):

- **Framework-agnostic core.** Factors and services are plain async Python with
  abstract persistence methods. `contrib/` packages depend on the core — never
  the reverse.
- **Tokens are opaque, prefixed, and stored hashed.** Only HMAC-SHA256 hashes
  hit the database.
- **MFA by construction.** Login is an *authentication session* that factors
  advance step by step; it completes only when no required factor remains.
- **PKCE + state + nonce** on every OAuth2/OIDC flow.

## Installation

```bash
pip install "aegistry[all]"            # everything
pip install "aegistry[fastapi,sqlalchemy,password]"
```

## Quickstart (FastAPI + SQLAlchemy)

```python
from aegistry.contrib.fastapi import AuthConfig, get_password_router, get_oauth2_login_router
from aegistry.contrib.sqlalchemy import create_tables

config = AuthConfig(success_redirect_url="/app")
tables = create_tables(metadata)  # or define your own tables/stores

app.include_router(
    get_password_router(
        factor_dependency=get_password_factor,
        authentication_session_service_dependency=get_authentication_session_service,
        session_service_dependency=get_session_service,
        identity_resolver_dependency=get_identity_resolver,
        config=config,
    ),
    prefix="/auth",
)
app.include_router(
    get_oauth2_login_router(
        identifier="google",
        factor_dependency=get_google_factor,
        authentication_session_service_dependency=get_authentication_session_service,
        session_service_dependency=get_session_service,
        identity_resolver_dependency=get_identity_resolver,
        scope=["openid", "email", "profile"],
        config=config,
    ),
    prefix="/auth",
)
```

Your app provides the *dependencies* (wired to your database session) and an
``IdentityResolver`` mapping verified emails to your user rows; aegistry
provides the flows. See ``tests/contrib/test_fastapi_routers.py`` for a
complete, runnable wiring.

### Provider notes

- **Google** — pure OIDC; `GoogleOAuth2Factor` validates id_tokens against
  Google's JWKS. Email arrives with `email_verified`.
- **LINE** — `LineOAuth2Factor` validates id_tokens through LINE's verify
  endpoint (web-login tokens are HS256-signed with the channel secret, so
  JWKS validation can't be used). The `email` scope requires applying for
  permission in the LINE Developers console, and LINE never returns
  `email_verified` — don't auto-link LINE accounts to existing users by
  email without an extra verification step.

## Status

Early scaffold — APIs unstable. See upstream reauth for the core roadmap.

## License

MIT. Contains code from reauth, © 2026 François Voron, MIT licensed.
