feat(backend): fait tourner les jetons de rafraîchissement et détecte leur réutilisation

Le jeton de rafraîchissement est une chaîne opaque de 256 bits, jamais un
JWT. Il doit être révocable, donc sa ligne en base existe de toute façon,
et le JWT n'ajouterait qu'un second chemin de signature. Surtout, la
séparation d'avec le jeton d'accès devient structurelle : un JWT ne
figure dans aucune ligne, une chaîne opaque échoue au décodage. La
confusion refresh-vers-accès, qui transforme une fenêtre de 15 minutes en
fenêtre de 7 jours, est impossible même si quelqu'un oublie le test.

Seule l'empreinte SHA-256 est stockée. Pas d'Argon2 : l'entrée fait
256 bits de CSPRNG, aucun dictionnaire ne l'atteint, et une KDF coûterait
17 ms à chaque rafraîchissement.

La rotation ne protège de rien par elle-même : elle rend la réutilisation
détectable, et c'est la détection qui termine le vol. Un jeton déjà
tourné révoque donc toute sa famille et laisse une trace dans
`audit_log` ; un jeton expiré, lui, ne révoque rien, ce n'est pas une
preuve de compromission. Les deux cas ont leur test.

La revendication est une seule instruction SQL avec RETURNING. Un SELECT
puis un UPDATE laisseraient une fenêtre où deux onglets réussissent la
même rotation ; le test d'intégration le prouve, ce qui est
indémontrable sur un double.

`expires_at` est absolu et hérité du prédécesseur : s'il glissait, la
promesse de sept jours serait fictive.

Corrige au passage un défaut trouvé par un test : une `HTTPException`
construit sa propre réponse, donc l'effacement du cookie posé sur la
`Response` injectée était perdu. Un navigateur gardait un cookie mort
après une détection de réutilisation.
This commit is contained in:
Johan LEROY
2026-09-15 14:49:30 +02:00
parent ef933bea1a
commit 1f6210698d
13 changed files with 1047 additions and 69 deletions
+3
View File
@@ -23,6 +23,7 @@ from app.core.security import decode_access_token as decode_token
from app.db.session import get_session
from app.repositories.audit_log import AuditLogRepository
from app.repositories.login_attempt import LoginAttemptRepository
from app.repositories.refresh_token import RefreshTokenRepository
from app.repositories.user import UserRepository
from app.services.auth import AuthService, LoginPolicy
@@ -95,6 +96,7 @@ def get_auth_service(
return AuthService(
users=UserRepository(session),
attempts=LoginAttemptRepository(session),
refresh_tokens=RefreshTokenRepository(session),
audit=AuditLogRepository(session),
hasher=hasher,
transaction=session,
@@ -105,6 +107,7 @@ def get_auth_service(
max_failures_per_ip=settings.login_max_failures_per_ip,
max_failures_per_identifier=settings.login_max_failures_per_identifier,
),
refresh_ttl=timedelta(seconds=settings.refresh_token_ttl_seconds),
)
+119 -12
View File
@@ -1,14 +1,59 @@
# Piège : le jeton de rafraîchissement ne quitte jamais le cookie httpOnly, et le jeton
# d'accès ne va jamais dans un cookie. C'est ce qui réduit la surface CSRF aux trois routes de
# ce module : partout ailleurs, le navigateur n'attache rien de lui-même.
from fastapi import APIRouter, Depends, HTTPException, Request, Response, status
from app.api.deps import AuthServiceDep, CurrentPrincipalDep, get_client_ip
from app.api.deps import (
AuthServiceDep,
CurrentPrincipalDep,
SettingsDep,
get_client_ip,
require_trusted_origin,
)
from app.core.cookies import RefreshCookie, cookie_name
from app.core.logging import get_logger
from app.schemas.auth import LoginRequest, PrincipalResponse, TokenResponse
from app.services.auth import InvalidCredentialsError, RateLimitedError
from app.services.auth import (
AuthenticatedSession,
InvalidCredentialsError,
RateLimitedError,
SessionRejectedError,
)
router = APIRouter()
logger = get_logger(__name__)
DETAIL_IDENTIFIANTS = "Identifiants invalides"
DETAIL_SESSION = "Session invalide"
def repond(
response: Response, settings: SettingsDep, session: AuthenticatedSession
) -> TokenResponse:
response.headers["Cache-Control"] = "no-store"
response.set_cookie(**RefreshCookie.build(settings, session.refresh_secret).as_kwargs())
return TokenResponse(
access_token=session.access_token,
expires_in=session.expires_in,
principal=PrincipalResponse.from_principal(session.principal),
)
# Piège : une `HTTPException` construit sa propre réponse, donc tout en-tête posé sur la
# `Response` injectée est perdu. L'effacement du cookie doit voyager avec l'exception,
# sans quoi un navigateur garderait un cookie mort après une détection de réutilisation.
def entete_de_suppression(settings: SettingsDep) -> str:
temoin = Response()
temoin.delete_cookie(**RefreshCookie.expired(settings).as_deletion_kwargs())
return temoin.headers["set-cookie"]
def lit_le_cookie(request: Request, settings: SettingsDep) -> str:
secret = request.cookies.get(cookie_name(settings))
if not secret:
raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED, detail=DETAIL_SESSION)
return secret
@router.post("/login", response_model=TokenResponse, summary="Ouvre une session")
@@ -16,19 +61,16 @@ async def login(
payload: LoginRequest,
request: Request,
response: Response,
settings: SettingsDep,
service: AuthServiceDep,
client_ip: str | None = Depends(get_client_ip),
) -> TokenResponse:
# Une réponse d'authentification ne doit jamais être conservée par un intermédiaire.
response.headers["Cache-Control"] = "no-store"
agent = request.headers.get("user-agent")
try:
session = await service.authenticate(
email=payload.email,
password=payload.password,
client_ip=client_ip,
user_agent=agent,
email=payload.email, password=payload.password, client_ip=client_ip, user_agent=agent
)
except RateLimitedError as erreur:
logger.warning("auth.rate_limited email=%s ip=%s", payload.email, client_ip)
@@ -44,11 +86,76 @@ async def login(
) from erreur
logger.info("auth.login.success user_id=%s ip=%s", session.principal.id, client_ip)
return TokenResponse(
access_token=session.access_token,
expires_in=session.expires_in,
principal=PrincipalResponse.from_principal(session.principal),
)
return repond(response, settings, session)
@router.post(
"/refresh",
response_model=TokenResponse,
summary="Fait tourner la session",
dependencies=[Depends(require_trusted_origin)],
)
async def refresh(
request: Request,
response: Response,
settings: SettingsDep,
service: AuthServiceDep,
client_ip: str | None = Depends(get_client_ip),
) -> TokenResponse:
response.headers["Cache-Control"] = "no-store"
try:
session = await service.refresh(
secret=lit_le_cookie(request, settings),
client_ip=client_ip,
user_agent=request.headers.get("user-agent"),
)
except SessionRejectedError as erreur:
logger.warning("auth.refresh.rejected ip=%s", client_ip)
raise HTTPException(
status_code=status.HTTP_401_UNAUTHORIZED,
detail=DETAIL_SESSION,
headers={
"Set-Cookie": entete_de_suppression(settings),
"Cache-Control": "no-store",
},
) from erreur
return repond(response, settings, session)
@router.post(
"/logout",
status_code=status.HTTP_204_NO_CONTENT,
summary="Ferme la session courante",
dependencies=[Depends(require_trusted_origin)],
)
async def logout(
request: Request, response: Response, settings: SettingsDep, service: AuthServiceDep
) -> None:
response.headers["Cache-Control"] = "no-store"
secret = request.cookies.get(cookie_name(settings))
if secret:
await service.logout(secret=secret)
response.delete_cookie(**RefreshCookie.expired(settings).as_deletion_kwargs())
@router.post(
"/logout-all",
status_code=status.HTTP_204_NO_CONTENT,
summary="Ferme toutes les sessions du compte",
dependencies=[Depends(require_trusted_origin)],
)
async def logout_all(
principal: CurrentPrincipalDep,
response: Response,
settings: SettingsDep,
service: AuthServiceDep,
) -> None:
response.headers["Cache-Control"] = "no-store"
revoquees = await service.logout_all(principal)
logger.info("auth.logout_all user_id=%s sessions=%s", principal.id, revoquees)
response.delete_cookie(**RefreshCookie.expired(settings).as_deletion_kwargs())
@router.get("/me", response_model=PrincipalResponse, summary="Décrit le compte connecté")
+7
View File
@@ -47,6 +47,13 @@ class RefreshCookie:
def as_kwargs(self) -> dict[str, Any]:
return asdict(self)
def as_deletion_kwargs(self) -> dict[str, Any]:
# `Response.delete_cookie()` n'accepte ni `value` ni `max_age`, mais il exige le même
# nom, le même chemin et les mêmes attributs, sinon le navigateur garde le cookie.
arguments = asdict(self)
del arguments["value"], arguments["max_age"]
return arguments
def cookie_name(settings: Settings) -> str:
if settings.cookies_are_secure:
+2 -1
View File
@@ -3,6 +3,7 @@
from app.models.audit_log import AuditLog
from app.models.login_attempt import LoginAttempt
from app.models.refresh_token import RefreshToken
from app.models.user import AppUser
__all__ = ["AppUser", "AuditLog", "LoginAttempt"]
__all__ = ["AppUser", "AuditLog", "LoginAttempt", "RefreshToken"]
+64
View File
@@ -0,0 +1,64 @@
# Pourquoi : un jeton de rafraîchissement est une chaîne opaque, jamais un JWT. Il doit être
# révocable, donc cette ligne existe de toute façon ; le JWT n'ajouterait qu'un second chemin de
# signature. Surtout, la séparation devient structurelle : un JWT ne figure dans aucune ligne,
# une chaîne opaque échoue au décodage. Aucune confusion de type n'est possible.
# Piège : `expires_at` est absolu et hérité du prédécesseur à chaque rotation. S'il glissait,
# la promesse de sept jours serait fictive et une session active ne finirait jamais.
import uuid
from datetime import datetime
from enum import StrEnum
from sqlalchemy import CheckConstraint, DateTime, ForeignKey, Index, LargeBinary, Text, func
from sqlalchemy.dialects.postgresql import INET
from sqlalchemy.dialects.postgresql import UUID as PG_UUID
from sqlalchemy.orm import Mapped, mapped_column
from app.db.base import Base
class RevocationReason(StrEnum):
DECONNEXION = "logout"
ROTATION = "rotation"
REUTILISATION = "reuse_detected"
CHANGEMENT_MOT_DE_PASSE = "password_change"
ADMINISTRATION = "admin"
MOTIFS_AUTORISES = ", ".join(f"'{motif.value}'" for motif in RevocationReason)
class RefreshToken(Base):
__tablename__ = "refresh_token"
__table_args__ = (
CheckConstraint(
f"revoked_reason is null or revoked_reason in ({MOTIFS_AUTORISES})",
name="ck_refresh_token_revoked_reason",
),
Index("ix_refresh_token_family", "family_id"),
Index("ix_refresh_token_user", "user_id"),
Index(
"ix_refresh_token_vivants",
"user_id",
postgresql_where="revoked_at is null and rotated_at is null",
),
)
id: Mapped[uuid.UUID] = mapped_column(
PG_UUID(as_uuid=True), primary_key=True, server_default=func.gen_random_uuid()
)
family_id: Mapped[uuid.UUID] = mapped_column(PG_UUID(as_uuid=True), nullable=False)
user_id: Mapped[uuid.UUID] = mapped_column(
PG_UUID(as_uuid=True), ForeignKey("app_user.id", ondelete="CASCADE"), nullable=False
)
token_hash: Mapped[bytes] = mapped_column(LargeBinary, nullable=False, unique=True)
issued_at: Mapped[datetime] = mapped_column(
DateTime(timezone=True), nullable=False, server_default=func.now()
)
expires_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), nullable=False)
rotated_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True), nullable=True)
revoked_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True), nullable=True)
revoked_reason: Mapped[str | None] = mapped_column(Text, nullable=True)
replaced_by: Mapped[uuid.UUID | None] = mapped_column(PG_UUID(as_uuid=True), nullable=True)
client_ip: Mapped[str | None] = mapped_column(INET, nullable=True)
user_agent: Mapped[str | None] = mapped_column(Text, nullable=True)
@@ -0,0 +1,106 @@
# Piège : `claim_for_rotation()` est une seule instruction. Un SELECT puis un UPDATE
# laisseraient une fenêtre où deux onglets réussissent la même rotation. Zéro ligne retournée
# signifie donc, sans ambiguïté, que le jeton était déjà tourné, révoqué, expiré ou inconnu, et
# c'est `inspect()` qui départage ensuite ces cas.
from dataclasses import dataclass
from datetime import datetime
from uuid import UUID
from sqlalchemy import func, select, update
from sqlalchemy.ext.asyncio import AsyncSession
from app.models.refresh_token import RefreshToken, RevocationReason
@dataclass(frozen=True, slots=True)
class ClaimedToken:
id: UUID
family_id: UUID
user_id: UUID
expires_at: datetime
class RefreshTokenRepository:
def __init__(self, session: AsyncSession) -> None:
self._session = session
async def create(
self,
*,
user_id: UUID,
family_id: UUID,
token_hash: bytes,
expires_at: datetime,
client_ip: str | None,
user_agent: str | None,
) -> RefreshToken:
jeton = RefreshToken(
user_id=user_id,
family_id=family_id,
token_hash=token_hash,
expires_at=expires_at,
client_ip=client_ip,
user_agent=user_agent,
)
self._session.add(jeton)
await self._session.flush()
return jeton
async def claim_for_rotation(self, token_hash: bytes) -> ClaimedToken | None:
requete = (
update(RefreshToken)
.where(
RefreshToken.token_hash == token_hash,
RefreshToken.rotated_at.is_(None),
RefreshToken.revoked_at.is_(None),
RefreshToken.expires_at > func.clock_timestamp(),
)
.values(
rotated_at=func.clock_timestamp(),
revoked_at=func.clock_timestamp(),
revoked_reason=RevocationReason.ROTATION.value,
)
.returning(
RefreshToken.id,
RefreshToken.family_id,
RefreshToken.user_id,
RefreshToken.expires_at,
)
)
ligne = (await self._session.execute(requete)).one_or_none()
if ligne is None:
return None
return ClaimedToken(
id=ligne.id,
family_id=ligne.family_id,
user_id=ligne.user_id,
expires_at=ligne.expires_at,
)
async def inspect(self, token_hash: bytes) -> RefreshToken | None:
requete = select(RefreshToken).where(RefreshToken.token_hash == token_hash)
return (await self._session.execute(requete)).scalar_one_or_none()
async def link_replacement(self, ancien_id: UUID, nouveau_id: UUID) -> None:
await self._session.execute(
update(RefreshToken).where(RefreshToken.id == ancien_id).values(replaced_by=nouveau_id)
)
async def revoke_family(self, family_id: UUID, reason: RevocationReason) -> int:
resultat = await self._session.execute(
update(RefreshToken)
.where(RefreshToken.family_id == family_id, RefreshToken.revoked_at.is_(None))
.values(revoked_at=func.clock_timestamp(), revoked_reason=reason.value)
.returning(RefreshToken.id)
)
return len(resultat.all())
async def revoke_all_for_user(self, user_id: UUID, reason: RevocationReason) -> int:
resultat = await self._session.execute(
update(RefreshToken)
.where(RefreshToken.user_id == user_id, RefreshToken.revoked_at.is_(None))
.values(revoked_at=func.clock_timestamp(), revoked_reason=reason.value)
.returning(RefreshToken.id)
)
return len(resultat.all())
+126 -13
View File
@@ -5,19 +5,30 @@
# vérification réelle. Sans lui, l'écart de temps de réponse est un oracle d'existence.
# Piège : la tentative échouée est validée en base AVANT que l'erreur ne soit levée.
# `get_session()` ne valide pas de lui-même, donc la preuve disparaîtrait avec la transaction.
# Piège : dans `refresh()`, un jeton expiré ne révoque PAS la famille, un jeton déjà tourné si.
# La rotation ne protège de rien par elle-même : elle rend la réutilisation détectable, et
# c'est la détection qui termine le vol.
from dataclasses import dataclass
from datetime import UTC, datetime, timedelta
from typing import NoReturn, Protocol
from uuid import UUID
from uuid import UUID, uuid4
from app.core.hashing import Argon2Hasher
from app.core.principal import Principal
from app.core.roles import AccountKind, Role
from app.core.security import TokenPolicy, encode_access_token
from app.models.audit_log import AuditAction
from app.core.security import (
TokenPolicy,
encode_access_token,
fingerprint_refresh,
generate_refresh_secret,
)
from app.models.audit_log import AuditAction, AuditOutcome
from app.models.login_attempt import LoginOutcome
from app.models.refresh_token import RevocationReason
from app.repositories.audit_log import AuditLogRepository
from app.repositories.login_attempt import LoginAttemptRepository
from app.repositories.refresh_token import RefreshTokenRepository
from app.repositories.user import UserRepository
@@ -33,6 +44,10 @@ class InvalidCredentialsError(AuthError):
pass
class SessionRejectedError(AuthError):
pass
class RateLimitedError(AuthError):
def __init__(self, retry_after: int) -> None:
super().__init__("Trop de tentatives")
@@ -52,6 +67,7 @@ class AuthenticatedSession:
principal: Principal
access_token: str
expires_in: int
refresh_secret: str
class AuthService:
@@ -60,19 +76,23 @@ class AuthService:
*,
users: UserRepository,
attempts: LoginAttemptRepository,
refresh_tokens: RefreshTokenRepository,
audit: AuditLogRepository,
hasher: Argon2Hasher,
transaction: Transaction,
token_policy: TokenPolicy,
login_policy: LoginPolicy,
refresh_ttl: timedelta,
) -> None:
self._users = users
self._attempts = attempts
self._refresh = refresh_tokens
self._audit = audit
self._hasher = hasher
self._transaction = transaction
self._token_policy = token_policy
self._login_policy = login_policy
self._refresh_ttl = refresh_ttl
async def authenticate(
self, *, email: str, password: str, client_ip: str | None, user_agent: str | None
@@ -101,19 +121,60 @@ class AuthService:
await self._attempts.record(
email=email, client_ip=client_ip, outcome=LoginOutcome.SUCCES, user_id=compte.id
)
secret = await self._ouvre_une_famille(
user_id=compte.id, client_ip=client_ip, user_agent=user_agent
)
await self._transaction.commit()
return self.issue_access_token(
Principal(
id=compte.id,
email=compte.email,
role=Role(compte.role),
kind=AccountKind(compte.kind),
must_change_password=compte.must_change_password,
)
)
return self._session(self._en_principal(compte), secret)
def issue_access_token(self, principal: Principal) -> AuthenticatedSession:
async def refresh(
self, *, secret: str, client_ip: str | None, user_agent: str | None
) -> AuthenticatedSession:
empreinte = fingerprint_refresh(secret)
revendique = await self._refresh.claim_for_rotation(empreinte)
if revendique is None:
await self._traite_rotation_refusee(empreinte, client_ip, user_agent)
compte = await self._users.get_by_id(revendique.user_id)
if compte is None or not compte.is_active:
await self._refresh.revoke_family(revendique.family_id, RevocationReason.ADMINISTRATION)
await self._transaction.commit()
raise SessionRejectedError("Session révoquée")
nouveau_secret = generate_refresh_secret()
nouveau = await self._refresh.create(
user_id=revendique.user_id,
family_id=revendique.family_id,
token_hash=fingerprint_refresh(nouveau_secret),
expires_at=revendique.expires_at,
client_ip=client_ip,
user_agent=user_agent,
)
await self._refresh.link_replacement(revendique.id, nouveau.id)
await self._transaction.commit()
return self._session(self._en_principal(compte), nouveau_secret)
async def logout(self, *, secret: str) -> None:
ligne = await self._refresh.inspect(fingerprint_refresh(secret))
if ligne is not None:
await self._refresh.revoke_family(ligne.family_id, RevocationReason.DECONNEXION)
await self._transaction.commit()
async def logout_all(self, principal: Principal) -> int:
revoquees = await self._refresh.revoke_all_for_user(
principal.id, RevocationReason.DECONNEXION
)
await self._audit.record(
action=AuditAction.SESSIONS_REVOQUEES,
actor=principal,
detail={"sessions_revoquees": revoquees},
)
await self._transaction.commit()
return revoquees
def _session(self, principal: Principal, refresh_secret: str) -> AuthenticatedSession:
jeton = encode_access_token(
self._token_policy,
subject=principal.id,
@@ -124,8 +185,59 @@ class AuthService:
principal=principal,
access_token=jeton,
expires_in=int(self._token_policy.access_ttl.total_seconds()),
refresh_secret=refresh_secret,
)
def _en_principal(self, compte: object) -> Principal:
return Principal(
id=compte.id, # type: ignore[attr-defined]
email=compte.email, # type: ignore[attr-defined]
role=Role(compte.role), # type: ignore[attr-defined]
kind=AccountKind(compte.kind), # type: ignore[attr-defined]
must_change_password=compte.must_change_password, # type: ignore[attr-defined]
)
async def _ouvre_une_famille(
self, *, user_id: UUID, client_ip: str | None, user_agent: str | None
) -> str:
secret = generate_refresh_secret()
await self._refresh.create(
user_id=user_id,
family_id=uuid4(),
token_hash=fingerprint_refresh(secret),
expires_at=datetime.now(UTC) + self._refresh_ttl,
client_ip=client_ip,
user_agent=user_agent,
)
return secret
async def _traite_rotation_refusee(
self, empreinte: bytes, client_ip: str | None, user_agent: str | None
) -> NoReturn:
ligne = await self._refresh.inspect(empreinte)
if ligne is None:
raise SessionRejectedError("Session inconnue")
if ligne.expires_at <= datetime.now(UTC):
raise SessionRejectedError("Session expirée")
# Présenter un jeton déjà tourné est une preuve de compromission, pas un accident : toute
# la famille tombe, y compris la session encore vivante du voleur ou de la victime.
revoquees = await self._refresh.revoke_family(
ligne.family_id, RevocationReason.REUTILISATION
)
await self._audit.record(
action=AuditAction.REFRESH_REUTILISE,
outcome=AuditOutcome.ECHEC,
target_type="refresh_token",
target_id=str(ligne.family_id),
client_ip=client_ip,
user_agent=user_agent,
detail={"famille": str(ligne.family_id), "sessions_revoquees": revoquees},
)
await self._transaction.commit()
raise SessionRejectedError("Session révoquée")
async def _refuse_si_limite(
self, *, email: str, client_ip: str | None, user_agent: str | None
) -> None:
@@ -148,6 +260,7 @@ class AuthService:
if compteurs.per_identifier >= politique.max_failures_per_identifier:
await self._audit.record(
action=AuditAction.LIMITE_PAR_IDENTIFIANT,
outcome=AuditOutcome.ECHEC,
actor_label=email.strip().lower(),
client_ip=client_ip,
user_agent=user_agent,