fastapi-fullauth 0.17.2__tar.gz → 0.18.0__tar.gz

{fastapi_fullauth-0.17.2 → fastapi_fullauth-0.18.0}/CHANGELOG.md

@@ -1,5 +1,27 @@
 # Changelog
 
+## 0.18.0
+
+### Added
+
+- **Two-factor authentication (TOTP).** The one row where the fastapi-users comparison read "none" for both libraries. Install with the new `mfa` extra, set `MFA_ISSUER`, pass an `mfa_model` to your adapter, and `/auth/mfa/enroll` plus `/auth/mfa/confirm` turn it on for a user; the recovery codes come back from the confirm call and are shown once. A correct password on an account that has it answers `202` with a short-lived `mfa_token` rather than a session, which `/auth/mfa/verify` exchanges for the real token pair along with a code or a recovery code. Enrolling and disabling ask for the same proof of presence as `DELETE /me`. See [the guide](https://mdfarhankc.github.io/fastapi-fullauth/mfa/).
+
+  The ways around a second factor are what make it worth having, so: a code is refused once its time step has been accepted, which also means the code that confirms enrolment is spent and signing in needs the next one; `/mfa/verify` has its own rate-limit bucket and counts failures against the account through the lockout manager, since six digits is a small space; one step of clock drift either side is allowed, as RFC 6238 recommends; the pending token is burned when it buys a session and is rejected anywhere a session token is expected; recovery codes are stored hashed and are single use.
+
+  **MFA gates password sign-in only.** Passkeys are already phishing-resistant and an OAuth provider runs its own second factor, which this library cannot inspect. The TOTP secret is stored in plaintext, as the OAuth provider tokens are; the threat model says so.
+
+- **`after_mfa_enabled` and `after_mfa_disabled` hooks,** both `async def(user)`. Turning a second factor off is what an attacker who has taken an account does first, so it is worth mailing about.
+- **`JWT_ISSUER` and `JWT_AUDIENCE`.** Several services signing with one `SECRET_KEY` had no way to tell whose token they were holding, so an access token minted for an admin tool was accepted by the public API. Set either one and every token the engine mints carries the claim, purpose-scoped tokens included, and decoding requires it. Both are off by default, and an unset `JWT_AUDIENCE` means the claim is not checked, so a deployment can enable it on the issuing side and roll the verifying side forward afterwards rather than needing both at once. **Once a service requires them, tokens minted before they were configured stop validating, so expect one round of sign-outs.** This closes a limitation the threat model has been carrying.
+
+### Fixed
+
+- **`pip install "fastapi-fullauth[sqlmodel]"` produced an installation that could not be imported.** The extra took `sqlmodel`, which depends on plain SQLAlchemy, and relied on SQLAlchemy installing greenlet by itself. SQLAlchemy 2.1 no longer does, so a fresh install resolved without greenlet and `import fastapi_fullauth` raised `ImportError` from the asyncio module. The extra now declares `sqlalchemy[asyncio]`, as the `sqlalchemy` extra always did. This affected 0.17.x installs made after SQLAlchemy 2.1 was released, not only this version.
+
+### Changed
+
+- **The SQLAlchemy model guidance no longer uses `lazy="noload"`.** SQLAlchemy 2.1 deprecates that strategy, so anyone who copied the documented `User` model from here saw a deprecation warning, and a failure outright if they treat warnings as errors. The documentation, the mixin docstring, the example app and the Agent Skill now use `relationship(lazy="raise", passive_deletes=True)`: nothing in the library reads `refresh_tokens`, so an accidental access should be a clear error rather than a lazy query in async code, and the cascade belongs to the `ON DELETE CASCADE` the mixin already declares. If you have the old line in your models, change it.
+- **Dependencies refreshed and verified against the newest releases,** including SQLAlchemy 2.1, pydantic 2.14, pydantic-settings 2.16, FastAPI 0.143.3, SQLModel 0.0.48, mypy 2.4 and ruff 0.17.1. The declared floors are unchanged, and `sqlalchemy>=2.0.49` was re-checked by running the adapter suites against 2.0.54 as well as 2.1.4.
+
 ## 0.17.2
 
 ### Fixed

{fastapi_fullauth-0.17.2 → fastapi_fullauth-0.18.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: fastapi-fullauth
-Version: 0.17.2
+Version: 0.18.0
 Summary: Production-grade, async-native authentication and authorization library for FastAPI
 Project-URL: Changelog, https://github.com/mdfarhankc/fastapi-fullauth/blob/main/CHANGELOG.md
 Project-URL: Documentation, https://mdfarhankc.github.io/fastapi-fullauth
@@ -36,8 +36,11 @@ Provides-Extra: beanie-standard
 Requires-Dist: bcrypt>=4.1.0; extra == 'beanie-standard'
 Requires-Dist: beanie>=2.0; extra == 'beanie-standard'
 Requires-Dist: httpx>=0.28.1; extra == 'beanie-standard'
+Requires-Dist: pyotp>=2.10.0; extra == 'beanie-standard'
 Requires-Dist: redis>=7.4.0; extra == 'beanie-standard'
 Requires-Dist: webauthn>=2.7.1; extra == 'beanie-standard'
+Provides-Extra: mfa
+Requires-Dist: pyotp>=2.10.0; extra == 'mfa'
 Provides-Extra: oauth
 Requires-Dist: httpx>=0.28.1; extra == 'oauth'
 Provides-Extra: passkey
@@ -51,17 +54,21 @@ Provides-Extra: sqlalchemy-standard
 Requires-Dist: alembic>=1.18.4; extra == 'sqlalchemy-standard'
 Requires-Dist: bcrypt>=4.1.0; extra == 'sqlalchemy-standard'
 Requires-Dist: httpx>=0.28.1; extra == 'sqlalchemy-standard'
+Requires-Dist: pyotp>=2.10.0; extra == 'sqlalchemy-standard'
 Requires-Dist: redis>=7.4.0; extra == 'sqlalchemy-standard'
 Requires-Dist: sqlalchemy[asyncio]>=2.0.49; extra == 'sqlalchemy-standard'
 Requires-Dist: webauthn>=2.7.1; extra == 'sqlalchemy-standard'
 Provides-Extra: sqlmodel
 Requires-Dist: alembic>=1.18.4; extra == 'sqlmodel'
+Requires-Dist: sqlalchemy[asyncio]>=2.0.49; extra == 'sqlmodel'
 Requires-Dist: sqlmodel>=0.0.38; extra == 'sqlmodel'
 Provides-Extra: sqlmodel-standard
 Requires-Dist: alembic>=1.18.4; extra == 'sqlmodel-standard'
 Requires-Dist: bcrypt>=4.1.0; extra == 'sqlmodel-standard'
 Requires-Dist: httpx>=0.28.1; extra == 'sqlmodel-standard'
+Requires-Dist: pyotp>=2.10.0; extra == 'sqlmodel-standard'
 Requires-Dist: redis>=7.4.0; extra == 'sqlmodel-standard'
+Requires-Dist: sqlalchemy[asyncio]>=2.0.49; extra == 'sqlmodel-standard'
 Requires-Dist: sqlmodel>=0.0.38; extra == 'sqlmodel-standard'
 Requires-Dist: webauthn>=2.7.1; extra == 'sqlmodel-standard'
 Provides-Extra: tortoise
@@ -69,6 +76,7 @@ Requires-Dist: tortoise-orm>=1.0; extra == 'tortoise'
 Provides-Extra: tortoise-standard
 Requires-Dist: bcrypt>=4.1.0; extra == 'tortoise-standard'
 Requires-Dist: httpx>=0.28.1; extra == 'tortoise-standard'
+Requires-Dist: pyotp>=2.10.0; extra == 'tortoise-standard'
 Requires-Dist: redis>=7.4.0; extra == 'tortoise-standard'
 Requires-Dist: tortoise-orm>=1.0; extra == 'tortoise-standard'
 Requires-Dist: webauthn>=2.7.1; extra == 'tortoise-standard'

{fastapi_fullauth-0.17.2 → fastapi_fullauth-0.18.0}/docs/adapters/sqlalchemy.md

@@ -46,9 +46,18 @@ class User(UserMixin, Base):
     roles: Mapped[list[Role]] = relationship(
         secondary="fullauth_user_roles", lazy="selectin",
     )
-    refresh_tokens: Mapped[list[RefreshToken]] = relationship(lazy="noload")
+    refresh_tokens: Mapped[list[RefreshToken]] = relationship(
+        lazy="raise", passive_deletes=True
+    )
 ```
 
+`roles` is eagerly loaded because the library reads it; `refresh_tokens` is not read
+at all, so `lazy="raise"` turns an accidental access into a clear error instead of
+a lazy query in async code, and `passive_deletes=True` leaves the cascade to the
+`ON DELETE CASCADE` the mixin already declares. (Earlier versions of this page
+used `lazy="noload"`, which SQLAlchemy deprecated in 2.1 because it silently
+returns nothing for related items.)
+
 `UserMixin` provides `id`, `email`, `hashed_password` (nullable; `NULL` for OAuth-only users), `is_active`, `is_verified`, `is_superuser`, `created_at`. For integer or string user keys, see [Choosing a primary key type](index.md#choosing-a-primary-key-type).
 
 ### 2. Create the adapter

{fastapi_fullauth-0.17.2 → fastapi_fullauth-0.18.0}/docs/auth/hooks.md

@@ -48,6 +48,8 @@ fullauth.hooks.on("after_register", on_register)
 | `after_email_verify` | `async def(user: UserSchema)` | After email is verified |
 | `after_oauth_login` | `async def(user: UserSchema, provider: str, is_new_user: bool)` | After OAuth login succeeds |
 | `after_oauth_register` | `async def(user: UserSchema, user_info: OAuthUserInfo)` | After a new user is created via OAuth |
+| `after_mfa_enabled` | `async def(user: UserSchema)` | After two-factor authentication is turned on |
+| `after_mfa_disabled` | `async def(user: UserSchema)` | After it is turned off |
 | `after_oauth_link` | `async def(user: UserSchema, provider: str)` | After a signed-in user links a provider |
 | `after_oauth_unlink` | `async def(user: UserSchema, provider: str)` | After a signed-in user unlinks a provider |
 | `send_verification_email` | `async def(email: str, token: str)` | When email verification is requested |

{fastapi_fullauth-0.17.2 → fastapi_fullauth-0.18.0}/docs/configuration.md

@@ -134,6 +134,8 @@ and `REAUTH_MAX_AGE_SECONDS` accept `0`, which means something for each of them.
 | Option | Type | Default | Description |
 |--------|------|---------|-------------|
 | `SECRET_KEY` | `str \| None` | `None` | JWT signing key. Auto-generated in dev if not set. |
+| `JWT_ISSUER` | `str \| None` | `None` | Written as `iss` on every token, and required when decoding. Set it when more than one service signs with the same `SECRET_KEY`. |
+| `JWT_AUDIENCE` | `str \| None` | `None` | Written as `aud` on every token, and required when decoding. Left unset, the claim is not checked, so you can enable it on the issuing side first. |
 | `ALGORITHM` | `str` | `"HS256"` | JWT signing algorithm. |
 
 ### Tokens
@@ -277,6 +279,14 @@ fullauth = FullAuth(config=config, adapter=adapter, backends=[backend])
 !!! tip
     Setting `FULLAUTH_REDIS_URL=redis://...` switches all subsystems to Redis at once; you don't also need `FULLAUTH_BACKEND=redis`. Override individual backends as needed (e.g. `LOCKOUT_BACKEND=memory` for local dev), or set `FULLAUTH_BACKEND=memory` to keep everything in-memory despite the URL.
 
+### Two-factor authentication
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `MFA_ENABLED` | `bool` | `False` | Mount the MFA routes and ask for a code at sign-in. Inferred as `True` when `MFA_ISSUER` is set. |
+| `MFA_ISSUER` | `str \| None` | `None` | The name an authenticator app shows beside the code. Required when enabled. |
+| `MFA_PENDING_EXPIRE_SECONDS` | `int` | `300` | How long the token handed out after a correct password stays usable. |
+
 ### Passkeys
 
 | Option | Type | Default | Description |

fastapi_fullauth-0.18.0/docs/mfa.md

@@ -0,0 +1,176 @@
+# Two-Factor Authentication (TOTP)
+
+A second factor on top of the password: the six-digit codes an authenticator app
+such as Google Authenticator, 1Password or Aegis produces. Off by default.
+
+## Installation
+
+```bash
+pip install "fastapi-fullauth[mfa]"
+```
+
+## Configuration
+
+```python
+config = FullAuthConfig(
+    SECRET_KEY="...",
+    MFA_ISSUER="Acme",  # the name shown beside the code in the app
+)
+```
+
+Setting `MFA_ISSUER` is taken as opting in, so `MFA_ENABLED` becomes `True` on its
+own. Set `MFA_ENABLED=False` explicitly to configure it while keeping the routes
+off.
+
+Your adapter needs the MFA model, exactly like passkeys:
+
+```python
+from fastapi_fullauth.models.sqlmodel import MFAMixin
+
+class MFA(MFAMixin, table=True):
+    pass
+
+adapter = SQLModelAdapter(session_maker, user_model=User, refresh_token_model=RefreshToken, mfa_model=MFA)
+```
+
+Without it the routes are not mounted, sign-in never asks for a code, and a
+warning says so at startup.
+
+## Routes
+
+| Method | Path | Auth | Description |
+|--------|------|------|-------------|
+| `GET` | `/auth/mfa` | session | Whether it is on, and how many recovery codes remain |
+| `POST` | `/auth/mfa/enroll` | session + recent | Start enrolment; returns the secret and provisioning URI |
+| `POST` | `/auth/mfa/confirm` | session | Finish enrolment with a code; returns the recovery codes |
+| `DELETE` | `/auth/mfa` | session + recent | Turn it off |
+| `POST` | `/auth/mfa/verify` | pending token | Exchange a code for the real token pair |
+
+"Recent" means the same proof `DELETE /me` asks for: the current password in the
+body, or a session whose credentials were checked within `REAUTH_MAX_AGE_SECONDS`.
+Adding and removing a second factor are account-security actions.
+
+## Enrolling
+
+```
+POST /api/v1/auth/mfa/enroll
+Authorization: Bearer <access token>
+```
+
+```json
+{
+  "secret": "JBSWY3DPEHPK3PXP",
+  "provisioning_uri": "otpauth://totp/Acme:user@example.com?secret=...&issuer=Acme"
+}
+```
+
+Render the URI as a QR code, or show the secret for manual entry. Nothing is live
+yet: the secret does nothing until a code proves the authenticator was set up,
+so an abandoned enrolment cannot lock anyone out. Starting again simply replaces
+it.
+
+```
+POST /api/v1/auth/mfa/confirm
+{"code": "123456"}
+```
+
+```json
+{"recovery_codes": ["a1b2-c3d4-e5f6", "..."]}
+```
+
+!!! warning "Show the recovery codes once"
+    They are stored hashed and cannot be shown again. Each one works instead of a
+    code, one time, for a user who has lost their authenticator. Tell the user to
+    save them before they close the page.
+
+## Signing in
+
+A correct password on an account with a second factor answers `202` instead of
+`200`, with a short-lived token rather than a session:
+
+```json
+{"mfa_required": true, "mfa_token": "eyJhbGciOi..."}
+```
+
+That token buys the right to submit a code and nothing else: it is rejected
+everywhere a session token is expected. Exchange it:
+
+```
+POST /api/v1/auth/mfa/verify
+{"mfa_token": "eyJhbGciOi...", "code": "123456"}
+```
+
+The response is an ordinary login response, with the access and refresh tokens.
+A recovery code goes in the same `code` field.
+
+### Client changes
+
+```javascript
+const r = await fetch("/api/v1/auth/login", { method: "POST", body: ... });
+const data = await r.json();
+
+if (r.status === 202) {
+  const code = await promptForCode();
+  const verified = await fetch("/api/v1/auth/mfa/verify", {
+    method: "POST",
+    headers: {"Content-Type": "application/json"},
+    body: JSON.stringify({ mfa_token: data.mfa_token, code }),
+  });
+  return verified.json();
+}
+return data;
+```
+
+## What is defended against
+
+- **A code used twice.** A code stays valid for its whole 30-second step, so
+  anyone who reads it over a shoulder has that long to use it. Accepting one
+  records its time step, and nothing at or below that step is accepted again.
+  One consequence worth knowing: the code that confirms enrolment is spent, so
+  signing in needs the next one.
+- **Guessing.** Six digits is a small space. `/mfa/verify` has its own rate-limit
+  bucket (`AUTH_RATE_LIMITS.mfa`, 5 a minute) and failures are counted against
+  the account through the lockout manager, so rotating addresses does not help.
+- **Clock drift.** One step either side of now is accepted, as RFC 6238
+  recommends. Wider would mean more codes valid at once.
+- **A pending token reused.** It is burned once it buys a session.
+- **Recovery codes.** Stored hashed, single use.
+
+## What it does not cover
+
+**MFA gates password sign-in only.** Passkeys are already phishing-resistant, and
+an OAuth provider runs its own second factor which this library cannot inspect.
+An account with a passkey or a linked provider can still sign in that way without
+a code, by design.
+
+The TOTP secret is stored in plaintext, as the OAuth provider tokens are. A
+database leak hands over the second factor along with everything else; see the
+[threat model](security/threat-model.md).
+
+## Event hooks
+
+```python
+@fullauth.hooks.on("after_mfa_enabled")
+async def on_enabled(user):
+    await audit.record(user.id, "two-factor enabled")
+
+
+@fullauth.hooks.on("after_mfa_disabled")
+async def on_disabled(user):
+    await notify(user.email, "Two-factor authentication was turned off")
+```
+
+Both are worth sending mail about: turning a second factor off is exactly what an
+attacker who has taken an account does first.
+
+## If a user is locked out
+
+A recovery code is the intended path. Failing that, an operator can clear the
+factor directly, which returns the account to password-only sign-in:
+
+```python
+await fullauth.adapter.delete_mfa(user_id)
+```
+
+There is deliberately no route for this: it would be a way around the second
+factor.

{fastapi_fullauth-0.17.2 → fastapi_fullauth-0.18.0}/docs/migrating-from-fastapi-users.md

@@ -16,7 +16,7 @@ The good news first: **password hashes carry over unchanged, and so does your us
 | Lockout, rate limiting, CSRF, security headers | none | built in |
 | User admin CRUD routes | `GET/PATCH/DELETE /{id}` | **not included**; write your own with `require_role`, or call the adapter |
 | Link an OAuth account while signed in | `get_oauth_associate_router` | `/oauth/{provider}/link/authorize` and `/link/callback`; sign-in linking on a provider-verified email is automatic on top |
-| MFA / TOTP | none | none |
+| MFA / TOTP | none | TOTP with recovery codes, [see the guide](mfa.md) |
 
 Read the [threat model](security/threat-model.md) before you commit: it states plainly what the library defends against and what stays your responsibility.
 

{fastapi_fullauth-0.17.2 → fastapi_fullauth-0.18.0}/docs/security/threat-model.md

@@ -52,6 +52,18 @@ the current password, or credentials checked within `REAUTH_MAX_AGE_SECONDS`
 credentials are checked and carried unchanged through refresh rotation, so
 refreshing a stolen token does not renew it.
 
+## Separating services that share a secret
+
+Without `JWT_ISSUER` and `JWT_AUDIENCE`, any service holding the same `SECRET_KEY`
+accepts tokens minted by any other: an access token for the admin tool works
+against the public API. Set them per service and each one accepts only its own
+tokens, password-reset links included.
+
+They are off by default, and an unset `JWT_AUDIENCE` means the claim is not
+checked, so you can turn it on at the issuing side and roll the verifying side
+forward afterwards. Once a service requires them, tokens minted before they were
+configured no longer validate, so expect one round of sign-outs.
+
 ## Your application's responsibilities
 
 - **Cross-site scripting.** Any token readable by JavaScript can be stolen by XSS. Prefer the cookie backend with `CSRFMiddleware` for browser apps, and use a Content Security Policy.
@@ -63,7 +75,6 @@ refreshing a stolen token does not renew it.
 
 These are tracked for future releases:
 
-- OAuth provider access and refresh tokens are stored in plaintext.
-- Tokens carry no `iss` or `aud` claim, so services sharing a `SECRET_KEY` accept each other's tokens.
+- OAuth provider access and refresh tokens, and TOTP secrets, are stored in plaintext. A database leak hands over the second factor along with the rest.
 - Pruning expired refresh tokens is available (`adapter.prune_expired_refresh_tokens()`) but has to be scheduled by the application; nothing runs it for you.
 - A password-reset link is invalidated by a password change, but not by a later reset *request*: the newest link and any still-unused older one both work until one of them is used.

{fastapi_fullauth-0.17.2 → fastapi_fullauth-0.18.0}/examples/sqlalchemy_app/models.py

@@ -30,4 +30,4 @@ class User(UserMixin, Base):
     phone: Mapped[str] = mapped_column(String(20), default="")
 
     roles: Mapped[list[Role]] = relationship(secondary="fullauth_user_roles", lazy="selectin")
-    refresh_tokens: Mapped[list[RefreshToken]] = relationship(lazy="noload")
+    refresh_tokens: Mapped[list[RefreshToken]] = relationship(lazy="raise", passive_deletes=True)

{fastapi_fullauth-0.17.2 → fastapi_fullauth-0.18.0}/fastapi_fullauth/__init__.py

@@ -1,4 +1,4 @@
-__version__ = "0.17.2"
+__version__ = "0.18.0"
 
 from fastapi_fullauth.config import AuthRateLimits, FullAuthConfig
 from fastapi_fullauth.fullauth import FullAuth

{fastapi_fullauth-0.17.2 → fastapi_fullauth-0.18.0}/fastapi_fullauth/adapters/__init__.py

@@ -20,6 +20,7 @@ from fastapi_fullauth.adapters.base import (
     PRIVILEGED_USER_FIELDS,
     AbstractUserAdapter,
     AdapterFeature,
+    MFAAdapterMixin,
     OAuthAdapterMixin,
     PasskeyAdapterMixin,
     PermissionAdapterMixin,
@@ -33,6 +34,7 @@ __all__ = [
     "AbstractUserAdapter",
     "AdapterFeature",
     "OAuthAdapterMixin",
+    "MFAAdapterMixin",
     "PasskeyAdapterMixin",
     "PermissionAdapterMixin",
     "RoleAdapterMixin",

{fastapi_fullauth-0.17.2 → fastapi_fullauth-0.18.0}/fastapi_fullauth/adapters/_sqlalchemy_base.py

@@ -24,6 +24,7 @@ from sqlalchemy.orm import selectinload
 from fastapi_fullauth.adapters.base import (
     AbstractUserAdapter,
     AdapterFeature,
+    MFAAdapterMixin,
     OAuthAdapterMixin,
     PasskeyAdapterMixin,
     PermissionAdapterMixin,
@@ -34,6 +35,7 @@ from fastapi_fullauth.adapters.base import (
 from fastapi_fullauth.exceptions import UserAlreadyExistsError
 from fastapi_fullauth.types import (
     CreateUserSchemaType,
+    MFACredential,
     OAuthAccount,
     PasskeyCredential,
     RefreshToken,
@@ -67,6 +69,7 @@ class _BaseSQLAlchemyAdapter(
     OAuthAdapterMixin,
     PasskeyAdapterMixin,
     SessionAdapterMixin,
+    MFAAdapterMixin,
 ):
     """Concrete async adapter logic shared by the SQLAlchemy and SQLModel adapters.
 
@@ -92,6 +95,7 @@ class _BaseSQLAlchemyAdapter(
         role_permission_model: Any = None,
         oauth_account_model: Any = None,
         passkey_model: Any = None,
+        mfa_model: Any = None,
         user_schema: type[UserSchemaType],
         create_user_schema: type[CreateUserSchemaType],
     ) -> None:
@@ -115,6 +119,7 @@ class _BaseSQLAlchemyAdapter(
         self._role_permission_model = role_permission_model
         self._oauth_account_model = oauth_account_model
         self._passkey_model = passkey_model
+        self._mfa_model = mfa_model
         self._user_schema = user_schema
         self._create_user_schema = create_user_schema
         self.validate_user_id_type()
@@ -131,6 +136,7 @@ class _BaseSQLAlchemyAdapter(
             self._user_role_model,
             self._oauth_account_model,
             self._passkey_model,
+            self._mfa_model,
         )
         types: dict[str, Any] = {}
         for model in related:
@@ -154,6 +160,7 @@ class _BaseSQLAlchemyAdapter(
         ),
         "OAuth": ("oauth_account_model",),
         "Passkeys": ("passkey_model",),
+        "Two-factor authentication": ("mfa_model",),
     }
 
     def _require(self, model: _T | None, feature: str) -> _T:
@@ -174,6 +181,7 @@ class _BaseSQLAlchemyAdapter(
             "permission": self._permission_model is not None,
             "oauth": self._oauth_account_model is not None,
             "passkey": self._passkey_model is not None,
+            "mfa": self._mfa_model is not None,
             "session": True,
         }.get(feature, False)
 
@@ -272,7 +280,9 @@ class _BaseSQLAlchemyAdapter(
         cannot do that through a helper, so a caller that needs the column type
         narrows it itself.
         """
-        return await AsyncSession.execute(session, statement)
+        # Called unbound with an untyped statement, so the stubs widen the
+        # result to Any; the runtime type is the Result this returns.
+        return cast("Result[Any]", await AsyncSession.execute(session, statement))
 
     def _user_query(self) -> Any:
         # Eager-load roles so _to_schema() can read user.roles outside the session
@@ -901,3 +911,107 @@ class _BaseSQLAlchemyAdapter(
             if row:
                 await session.delete(row)
                 await self._commit(session)
+
+    # ── Two-factor authentication ────────────────────────────────────
+
+    def _to_mfa(self, row: Any) -> MFACredential:
+        return MFACredential(
+            user_id=row.user_id,
+            secret=row.secret,
+            confirmed_at=row.confirmed_at,
+            last_counter=row.last_counter,
+            recovery_codes=row.recovery_codes.split(",") if row.recovery_codes else [],
+            created_at=row.created_at,
+        )
+
+    async def get_mfa(self, user_id: UserID) -> MFACredential | None:
+        mfa_model = self._require(self._mfa_model, "Two-factor authentication")
+        async with self._begin() as session:
+            result = await self._execute(
+                session, select(mfa_model).where(mfa_model.user_id == user_id)
+            )
+            row = result.scalars().first()
+            return self._to_mfa(row) if row else None
+
+    async def store_mfa(self, data: MFACredential) -> MFACredential:
+        mfa_model = self._require(self._mfa_model, "Two-factor authentication")
+        async with self._begin() as session:
+            # Replace rather than conflict: restarting an abandoned enrolment is
+            # normal. A confirmed row is protected by the flow, not here.
+            await self._execute(session, delete(mfa_model).where(mfa_model.user_id == data.user_id))
+            session.add(
+                mfa_model(
+                    user_id=data.user_id,
+                    secret=data.secret,
+                    confirmed_at=data.confirmed_at,
+                    last_counter=data.last_counter,
+                    recovery_codes=",".join(data.recovery_codes),
+                )
+            )
+            await self._commit(session)
+            return data
+
+    async def confirm_mfa(self, user_id: UserID, recovery_codes: list[str]) -> None:
+        mfa_model = self._require(self._mfa_model, "Two-factor authentication")
+        async with self._begin() as session:
+            await self._execute(
+                session,
+                update(mfa_model)
+                .where(mfa_model.user_id == user_id)
+                .values(
+                    confirmed_at=datetime.now(timezone.utc),
+                    recovery_codes=",".join(recovery_codes),
+                ),
+            )
+            await self._commit(session)
+
+    async def delete_mfa(self, user_id: UserID) -> None:
+        mfa_model = self._require(self._mfa_model, "Two-factor authentication")
+        async with self._begin() as session:
+            await self._execute(session, delete(mfa_model).where(mfa_model.user_id == user_id))
+            await self._commit(session)
+
+    async def advance_mfa_counter(self, user_id: UserID, counter: int) -> bool:
+        mfa_model = self._require(self._mfa_model, "Two-factor authentication")
+        async with self._begin() as session:
+            result = cast(
+                "CursorResult[Any]",
+                await self._execute(
+                    session,
+                    update(mfa_model)
+                    .where(mfa_model.user_id == user_id)
+                    .where(mfa_model.last_counter < counter)
+                    .values(last_counter=counter),
+                ),
+            )
+            await self._commit(session)
+            return result.rowcount == 1
+
+    async def consume_recovery_code(self, user_id: UserID, code_hash: str) -> bool:
+        mfa_model = self._require(self._mfa_model, "Two-factor authentication")
+        async with self._begin() as session:
+            result = await self._execute(
+                session, select(mfa_model).where(mfa_model.user_id == user_id)
+            )
+            row = result.scalars().first()
+            if row is None or not row.recovery_codes:
+                return False
+            codes = row.recovery_codes.split(",")
+            if code_hash not in codes:
+                return False
+            codes.remove(code_hash)
+
+            # Conditional on the value we read, so two callers redeeming the same
+            # code cannot both win: the loser's WHERE no longer matches.
+            updated = cast(
+                "CursorResult[Any]",
+                await self._execute(
+                    session,
+                    update(mfa_model)
+                    .where(mfa_model.user_id == user_id)
+                    .where(mfa_model.recovery_codes == row.recovery_codes)
+                    .values(recovery_codes=",".join(codes)),
+                ),
+            )
+            await self._commit(session)
+            return updated.rowcount == 1

{fastapi_fullauth-0.17.2 → fastapi_fullauth-0.18.0}/fastapi_fullauth/adapters/base.py

@@ -11,6 +11,7 @@ from pydantic import BaseModel, TypeAdapter
 
 from fastapi_fullauth.types import (
     CreateUserSchemaType,
+    MFACredential,
     OAuthAccount,
     PasskeyCredential,
     RefreshToken,
@@ -19,7 +20,7 @@ from fastapi_fullauth.types import (
     UserSchemaType,
 )
 
-AdapterFeature = Literal["role", "permission", "oauth", "passkey", "session"]
+AdapterFeature = Literal["role", "permission", "oauth", "passkey", "session", "mfa"]
 
 # Columns only the library may set when creating a user. A CreateUserSchema that
 # exposes them would otherwise let a registering client grant itself admin,
@@ -400,6 +401,46 @@ class PasskeyAdapterMixin(ABC):
     async def delete_passkey(self, passkey_id: UUID) -> None: ...
 
 
+class MFAAdapterMixin(ABC):
+    """Mixin for TOTP second factors. Inherit alongside AbstractUserAdapter."""
+
+    @abstractmethod
+    async def get_mfa(self, user_id: UserID) -> MFACredential | None: ...
+
+    @abstractmethod
+    async def store_mfa(self, data: MFACredential) -> MFACredential:
+        """Create or replace the user's credential.
+
+        Replacing is how a restarted enrolment works, so this must overwrite an
+        unconfirmed row rather than conflict with it.
+        """
+        ...
+
+    @abstractmethod
+    async def confirm_mfa(self, user_id: UserID, recovery_codes: list[str]) -> None:
+        """Mark the credential live and store the hashed recovery codes."""
+        ...
+
+    @abstractmethod
+    async def delete_mfa(self, user_id: UserID) -> None: ...
+
+    @abstractmethod
+    async def advance_mfa_counter(self, user_id: UserID, counter: int) -> bool:
+        """Atomically move the accepted time step forward.
+
+        Must be a compare-and-swap: return True only when this call moved
+        ``last_counter`` to a strictly greater value. A code stays valid for its
+        whole time step, so returning False is what stops the same code being
+        replayed, exactly as the passkey sign-count does.
+        """
+        ...
+
+    @abstractmethod
+    async def consume_recovery_code(self, user_id: UserID, code_hash: str) -> bool:
+        """Atomically remove one hashed recovery code. True if this call removed it."""
+        ...
+
+
 # Maps the feature names used by supports_feature() to the mixin that implements
 # them. Defined after the mixins so the references resolve.
 _FEATURE_MIXINS: dict[str, type] = {
@@ -408,4 +449,5 @@ _FEATURE_MIXINS: dict[str, type] = {
     "oauth": OAuthAdapterMixin,
     "passkey": PasskeyAdapterMixin,
     "session": SessionAdapterMixin,
+    "mfa": MFAAdapterMixin,
 }