aegistry 0.1.0__tar.gz

aegistry-0.1.0/.gitignore

@@ -0,0 +1,12 @@
+__pycache__/
+*.pyc
+.venv/
+dist/
+.coverage
+.pytest_cache/
+.ruff_cache/
+node_modules/
+clients/packages/*/dist/
+.next/
+demo.db
+.env

aegistry-0.1.0/LICENSE

@@ -0,0 +1,22 @@
+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.
+

aegistry-0.1.0/PKG-INFO

@@ -0,0 +1,171 @@
+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.

aegistry-0.1.0/README.md

@@ -0,0 +1,119 @@
+# 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.

aegistry-0.1.0/aegistry/__init__.py

@@ -0,0 +1,7 @@
+"""The authentication toolkit for Python"""
+
+from aegistry.logging import configure_logger, get_logger
+
+__version__ = "0.1.0"
+
+__all__ = ["__version__", "configure_logger", "get_logger"]

aegistry-0.1.0/aegistry/amr.py

@@ -0,0 +1,102 @@
+"""Authentication Method Reference Values (amr) per RFC 8176.
+
+This module defines the standard Authentication Method Reference values
+as specified in RFC 8176 for use in JWT amr claims. These values represent
+the authentication methods used in an authentication event.
+
+See: https://datatracker.ietf.org/doc/html/rfc8176
+"""
+
+from enum import StrEnum
+
+
+class AuthenticationMethodReference(StrEnum):
+    """Standard Authentication Method Reference values (amr) per RFC 8176.
+
+    These values are used in the 'amr' claim of JSON Web Tokens (JWT) to
+    identify the authentication methods used in an authentication event.
+
+    Each value represents a family of closely related authentication methods.
+    The registry is maintained by IANA and is extensible.
+    """
+
+    # Biometric methods
+    FACE = "face"
+    """Facial recognition biometric authentication."""
+
+    FPT = "fpt"
+    """Fingerprint biometric authentication."""
+
+    IRIS = "iris"
+    """Iris scan biometric authentication."""
+
+    RETINA = "retina"
+    """Retina scan biometric authentication."""
+
+    VBM = "vbm"
+    """Voice biometric authentication."""
+
+    # Knowledge-based methods
+    KBA = "kba"
+    """Knowledge-based authentication (e.g., security questions)."""
+
+    PIN = "pin"
+    """Personal Identification Number or pattern authentication."""
+
+    PWD = "pwd"
+    """Password-based authentication."""
+
+    # Possession-based methods
+    HWK = "hwk"
+    """Proof-of-Possession of a hardware-secured key."""
+
+    OTP = "otp"
+    """One-time password (HOTP/TOTP)."""
+
+    SC = "sc"
+    """Smart card authentication."""
+
+    SWK = "swk"
+    """Proof-of-Possession of a software-secured key."""
+
+    # Out-of-band methods
+    SMS = "sms"
+    """SMS text message confirmation."""
+
+    TEL = "tel"
+    """Telephone call confirmation."""
+
+    EMAIL = "email"
+    """Email-based OTP or magic link authentication.
+
+    This is a custom extension to RFC 8176, not part of the standard.
+    """
+
+    OAUTH2 = "oauth2"
+    """OAuth 2.0 authentication, including social login.
+
+    This is a custom extension to RFC 8176, not part of the standard.
+    """
+
+    # Multi-factor and risk-based methods
+    MFA = "mfa"
+    """Multiple-factor authentication."""
+
+    MCA = "mca"
+    """Multiple-channel authentication."""
+
+    RBA = "rba"
+    """Risk-based authentication."""
+
+    # Special purpose
+    GEO = "geo"
+    """Geolocation-based authentication."""
+
+    USER = "user"
+    """User presence test."""
+
+    WIA = "wia"
+    """Windows Integrated Authentication."""
+
+
+__all__ = ["AuthenticationMethodReference"]