hexcore 11.3.0__tar.gz → 11.4.0__tar.gz

{hexcore-11.3.0/hexcore.egg-info → hexcore-11.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hexcore
-Version: 11.3.0
+Version: 11.4.0
 Summary: Reusable core for Python projects with hexagonal architecture, DDD, CQRS and background tasks. Ships the abstractions and the infrastructure: SQL session layer, FastAPI factories, worker runner, dynamic cron and identity.
 Author-email: "David Latosefki (Indroic)" <indroic@outlook.com>
 License-Expression: MIT

{hexcore-11.3.0 → hexcore-11.4.0}/hexcore/darwin/application/services.py

@@ -381,6 +381,20 @@ class SessionService:
             impersonation=impersonacion,
         )
 
+    async def previous_session_ids(self, session_id: UUID, *, limit: int = 100) -> list[UUID]:
+        """
+        Los `sid` de las sesiones **anteriores** de la familia de `session_id` (sin incluirla).
+
+        Existe para que `CsrfMiddleware` reconozca un token anti-CSRF que fue válido para la
+        sesión que el refresh acaba de reemplazar. Lee la base, pero sólo en el camino de
+        rechazo y con tope: el camino feliz de un request no lo llama.
+        """
+        sesion = await self._sessions.get(session_id)
+        if sesion is None:
+            return []
+        ids = await self._sessions.list_family_session_ids(sesion.family_id, limit=limit)
+        return [sid for sid in ids if sid != session_id]
+
     # ── Rotar ─────────────────────────────────────────────────────────────────
     async def refresh(
         self, refresh_token: str, *, transport: Transport

{hexcore-11.3.0 → hexcore-11.4.0}/hexcore/darwin/domain/exceptions.py

@@ -36,6 +36,8 @@ __all__ = [
     "EmailNotVerifiedError",
     "ImpersonationNotPermittedError",
     "CsrfValidationError",
+    "CSRF_CODE_INVALID",
+    "CSRF_CODE_PREVIOUS_SESSION",
     # ── Estado (409 / 423) ──
     "EmailAlreadyRegisteredError",
     "UsernameAlreadyTakenError",
@@ -164,14 +166,35 @@ class ImpersonationNotPermittedError(AuthorizationError):
     """
 
 
+#: `code` de un rechazo de CSRF cuyo token no verifica contra la sesión en curso ni contra
+#: ninguna anterior de su familia: lo mandó alguien que no lo recibió del servidor.
+CSRF_CODE_INVALID = "CsrfTokenInvalid"
+
+#: `code` de un rechazo de CSRF cuyo token **sí** fue válido, pero de una sesión anterior de la
+#: misma familia de rotación: el cliente firmó antes de que un refresh rotara el `sid`. Es el
+#: caso que se arregla pidiendo el token vigente (`GET /auth/csrf`) y reintentando.
+CSRF_CODE_PREVIOUS_SESSION = "CsrfTokenFromPreviousSession"
+
+
 class CsrfValidationError(AuthorizationError):
     """
     Falló el chequeo anti-CSRF del transporte por cookie.
 
     Sólo aplica al camino de cookie: un cliente Bearer manda el token a propósito en cada
     petición, así que no hay nada que falsificar desde otro origen.
+
+    `code` distingue, **cuando el rechazo es por el token**, entre `CSRF_CODE_INVALID` y
+    `CSRF_CODE_PREVIOUS_SESSION`; viaja en el cuerpo del 403 junto a `error`
+    (`CsrfValidationError`, que sigue siendo el discriminante). Es `None` cuando el rechazo
+    no es por el token (un origen en el que no se confía), porque ahí no hay nada que
+    recuperar. No revela nada útil a un atacante: sólo se llega a `CSRF_CODE_PREVIOUS_SESSION`
+    mandando un token que el servidor ya emitió para esa misma familia de sesiones.
     """
 
+    def __init__(self, *args: object, code: str | None = None) -> None:
+        super().__init__(*args)
+        self.code = code
+
 
 # ── Estado del recurso ────────────────────────────────────────────────────────
 class EmailAlreadyRegisteredError(IdentityError):

{hexcore-11.3.0 → hexcore-11.4.0}/hexcore/darwin/domain/ports.py

@@ -187,6 +187,26 @@ class AbstractSessionRepository(abc.ABC):
     async def revoke(self, session_id: UUID, *, at: datetime, reason: str) -> None:
         raise NotImplementedError
 
+    async def list_family_session_ids(
+        self, family_id: UUID, *, limit: int = 100
+    ) -> "list[UUID]":
+        """
+        Los `id` de las sesiones de una familia de rotación, las **más recientes primero**, con
+        tope de `limit`.
+
+        Sólo lo usa `CsrfMiddleware` para clasificar un rechazo de CSRF: reconocer que el token
+        que llegó era de una sesión anterior de la familia (el cliente firmó antes de que un
+        refresh rotara el `sid`). Incluye revocadas y consumidas: justamente las anteriores lo
+        están.
+
+        **No es abstracto a propósito**: es un puerto agregado después, y volverlo abstracto
+        rompería a todo repositorio propio ya escrito. La implementación por defecto devuelve
+        `[]`, y entonces el rechazo se clasifica siempre como token inválido: el comportamiento
+        (403) no cambia, sólo se pierde el `code` más específico.
+        """
+        del family_id, limit
+        return []
+
     @abc.abstractmethod
     async def revoke_family(self, family_id: UUID, *, at: datetime, reason: str) -> int:
         """

{hexcore-11.3.0 → hexcore-11.4.0}/hexcore/darwin/infrastructure/api/dependencies.py

@@ -194,13 +194,17 @@ def identity_exception_payload(exc: Exception) -> t.Mapping[str, t.Any]:
     Darwin) devuelve sólo lo del núcleo en vez de lanzar — mismo trato que `_mapa_de_plugins()`
     en `app.py`.
     """
-    from hexcore.darwin.domain.exceptions import AccessDeniedError
+    from hexcore.darwin.domain.exceptions import AccessDeniedError, CsrfValidationError
 
     base: dict[str, t.Any] = {}
     if isinstance(exc, AccessDeniedError):
         # Sólo `required`: `Decision.reason` es interno y nunca llega al cliente. Ver el
         # docstring de `AccessDeniedError`.
         base["required"] = exc.required
+    elif isinstance(exc, CsrfValidationError) and exc.code is not None:
+        # El mismo `code` que `CsrfMiddleware` pone en su 403, para que un rechazo de CSRF
+        # lanzado desde un handler tenga la misma forma que el del middleware.
+        base["code"] = exc.code
 
     from hexcore.darwin.application.container import get_identity_container
 

{hexcore-11.3.0 → hexcore-11.4.0}/hexcore/darwin/infrastructure/api/middlewares.py

@@ -25,7 +25,12 @@ from starlette.requests import Request
 from starlette.responses import JSONResponse, Response
 
 from hexcore.darwin.domain.context import AUTH_CONTEXT
-from hexcore.darwin.domain.exceptions import CsrfValidationError, IdentityError
+from hexcore.darwin.domain.exceptions import (
+    CSRF_CODE_INVALID,
+    CSRF_CODE_PREVIOUS_SESSION,
+    CsrfValidationError,
+    IdentityError,
+)
 
 if t.TYPE_CHECKING:
     from hexcore.darwin.application.config import IdentityConfig
@@ -224,13 +229,74 @@ class CsrfMiddleware(BaseHTTPMiddleware):
             logger.info(
                 "CSRF rechazado en %s %s: %s", request.method, request.url.path, exc
             )
-            return JSONResponse(
-                status_code=403,
-                content={"detail": str(exc), "error": type(exc).__name__},
-            )
+            if exc.code == CSRF_CODE_INVALID and await self._es_de_sesion_anterior(
+                request, contenedor
+            ):
+                exc = CsrfValidationError(
+                    "El token anti-CSRF del header es de una sesión anterior: el refresh "
+                    "rotó la sesión después de que el cliente lo obtuvo. Pedí el vigente con "
+                    "`GET /auth/csrf` y repetí la petición.",
+                    code=CSRF_CODE_PREVIOUS_SESSION,
+                )
+            content: dict[str, t.Any] = {"detail": str(exc), "error": type(exc).__name__}
+            if exc.code is not None:
+                content["code"] = exc.code
+            return JSONResponse(status_code=403, content=content)
 
         return await call_next(request)
 
+    async def _es_de_sesion_anterior(
+        self, request: Request, contenedor: t.Any
+    ) -> bool:
+        """
+        Si el token del header fue el de una sesión **anterior de la misma familia** que la de
+        la cookie de acceso.
+
+        Sólo corre al rechazar, así que el camino feliz de un request no paga la lectura de la
+        base. Tiene que ser **mejor esfuerzo**: cualquier fallo (credencial que no autentica,
+        base caída, un backend sin `list_family_session_ids`) devuelve `False` y el rechazo
+        sale como token inválido, que es lo que habría salido sin esta clasificación. Nunca
+        convierte un 403 en un 500.
+        """
+        from hexcore.darwin.infrastructure.hashing import compare_hashes, derive_csrf_token
+
+        enviado = request.headers.get(CSRF_HEADER)
+        clave = contenedor.config.secret_key
+        if not enviado or clave is None:
+            return False
+
+        try:
+            auth = auth_from_request(request)
+            if auth is None:
+                from hexcore.darwin.infrastructure.transports import TransportResolver
+
+                transporte = TransportResolver(cookies=contenedor.config.cookies).resolve(
+                    request
+                )
+                token = transporte.extract_access(request)
+                if token is None:
+                    return False
+                auth = await contenedor.session_service().authenticate(
+                    token, transport=transporte.name
+                )
+
+            sid = getattr(auth.actor, "session_id", None)
+            if sid is None or auth.transport != "cookie":
+                return False
+
+            secreto = clave.get_secret_value()
+            previas = await contenedor.session_service().previous_session_ids(sid)
+            # Se recorren **todas** sin cortar en la primera que coincide: el tiempo no tiene
+            # que depender de cuál era (aunque `compare_hashes` ya es en tiempo constante).
+            coincide = False
+            for previa in previas:
+                if compare_hashes(enviado, derive_csrf_token(str(previa), secreto)):
+                    coincide = True
+            return coincide
+        except Exception:
+            logger.debug("No se pudo clasificar el rechazo de CSRF.", exc_info=True)
+            return False
+
     def _exento(self, request: Request) -> bool:
         if request.method.upper() in SAFE_METHODS:
             return True
@@ -262,14 +328,16 @@ class CsrfMiddleware(BaseHTTPMiddleware):
         if not enviado or not esperado:
             raise CsrfValidationError(
                 f"Falta el chequeo anti-CSRF: la petición tiene que mandar el header "
-                f"'{CSRF_HEADER}' con el mismo valor que la cookie de CSRF."
+                f"'{CSRF_HEADER}' con el mismo valor que la cookie de CSRF.",
+                code=CSRF_CODE_INVALID,
             )
 
         from hexcore.darwin.infrastructure.hashing import compare_hashes
 
         if not compare_hashes(enviado, esperado):
             raise CsrfValidationError(
-                "El valor anti-CSRF del header no coincide con el de la cookie."
+                "El valor anti-CSRF del header no coincide con el de la cookie.",
+                code=CSRF_CODE_INVALID,
             )
 
     @staticmethod

{hexcore-11.3.0 → hexcore-11.4.0}/hexcore/darwin/infrastructure/orms/beanie/repositories.py

@@ -245,6 +245,18 @@ class BeanieSessionRepository(_BaseBeanieRepository, AbstractSessionRepository):
             {"$set": {"revoked_at": at, "updated_at": datetime.now(UTC)}}
         )
 
+    async def list_family_session_ids(
+        self, family_id: UUID, *, limit: int = 100
+    ) -> list[UUID]:
+        """Los `id` de la familia, las más recientes primero. Ver el puerto."""
+        docs = (
+            await self._doc.find(self._doc.family_id == family_id)
+            .sort("-created_at")
+            .limit(limit)
+            .to_list()
+        )
+        return [doc.entity_id for doc in docs]
+
     async def revoke_family(
         self, family_id: UUID, *, at: datetime, reason: str
     ) -> int:

{hexcore-11.3.0 → hexcore-11.4.0}/hexcore/darwin/infrastructure/orms/sqlalchemy/repositories.py

@@ -221,6 +221,19 @@ class SqlAlchemySessionRepository(_BaseIdentityRepository, AbstractSessionReposi
             )
             await session.commit()
 
+    async def list_family_session_ids(
+        self, family_id: UUID, *, limit: int = 100
+    ) -> list[UUID]:
+        """Los `id` de la familia, las más recientes primero. Ver el puerto."""
+        async with self._session_scope() as session:
+            resultado = await session.execute(
+                select(self._model.id)
+                .where(self._model.family_id == family_id)
+                .order_by(self._model.created_at.desc())
+                .limit(limit)
+            )
+            return list(resultado.scalars().all())
+
     async def revoke_family(
         self, family_id: UUID, *, at: datetime, reason: str
     ) -> int:

{hexcore-11.3.0 → hexcore-11.4.0}/hexcore/darwin/testing/fakes.py

@@ -259,6 +259,15 @@ class FakeSessionRepository(AbstractSessionRepository):
                 )
                 self.reasons[session_id] = reason
 
+    async def list_family_session_ids(
+        self, family_id: UUID, *, limit: int = 100
+    ) -> list[UUID]:
+        """Los `id` de la familia, las más recientes primero. Ver el puerto."""
+        with self._lock:
+            familia = [s for s in self._por_id.values() if s.family_id == family_id]
+        familia.sort(key=lambda s: s.created_at, reverse=True)
+        return [s.id for s in familia[:limit]]
+
     async def revoke_family(
         self, family_id: UUID, *, at: datetime, reason: str
     ) -> int:

{hexcore-11.3.0 → hexcore-11.4.0/hexcore.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hexcore
-Version: 11.3.0
+Version: 11.4.0
 Summary: Reusable core for Python projects with hexagonal architecture, DDD, CQRS and background tasks. Ships the abstractions and the infrastructure: SQL session layer, FastAPI factories, worker runner, dynamic cron and identity.
 Author-email: "David Latosefki (Indroic)" <indroic@outlook.com>
 License-Expression: MIT

{hexcore-11.3.0 → hexcore-11.4.0}/pyproject.toml

@@ -10,7 +10,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "hexcore"
-version = "11.3.0"
+version = "11.4.0"
 authors = [
   { name="David Latosefki (Indroic)", email="indroic@outlook.com" },
 ]

{hexcore-11.3.0 → hexcore-11.4.0}/tests/test_darwin_http.py

@@ -1006,3 +1006,193 @@ def test_una_app_sin_el_feature_no_resuelve_credenciales(contenedor):
     r = TestClient(app).get("/x")
 
     assert r.json()["hay_contexto"] is False
+
+
+# ── 2c. CSRF y rotación de sesión (HC-01) ─────────────────────────────────────
+#
+# El refresh rota la sesión: crea una con `sid` nuevo, y el token anti-CSRF es `HMAC(sid)`. Una
+# petición firmada **antes** del refresh llega con el token de la sesión anterior y se rechaza
+# con 403. Es un caso distinto de un token inventado, y el cliente lo resuelve pidiendo el token
+# vigente: por eso el 403 lleva un `code` que los distingue.
+CODIGO_SESION_ANTERIOR = "CsrfTokenFromPreviousSession"
+CODIGO_INVALIDO = "CsrfTokenInvalid"
+
+
+def _escribir(client: TestClient, token: str | None):
+    """Una escritura por cookie con el token dado en el header (o sin header si es `None`)."""
+    headers = {"Origin": ORIGEN}
+    if token is not None:
+        headers[CSRF_HEADER] = token
+    return client.post("/auth/sign-out", headers=headers)
+
+
+def test_el_refresh_entrega_siempre_el_token_csrf_de_la_sesion_nueva(client, contenedor):
+    _alta(client)
+    anterior = _sign_in_cookie(client).headers[CSRF_HEADER]
+
+    r = client.post("/auth/refresh", headers=_csrf_headers(client))
+
+    assert r.status_code == 200, r.text
+    sid_nuevo = r.json()["session_id"]
+    assert r.headers[CSRF_HEADER] == derive_csrf_token(sid_nuevo, CLAVE)
+    assert r.headers[CSRF_HEADER] != anterior
+
+
+def test_un_token_de_una_sesion_anterior_de_la_familia_tiene_su_propio_code(client, contenedor):
+    _alta(client)
+    anterior = _sign_in_cookie(client).headers[CSRF_HEADER]
+    r = client.post("/auth/refresh", headers=_csrf_headers(client))
+    assert r.status_code == 200, r.text
+
+    r = _escribir(client, anterior)
+
+    assert r.status_code == 403
+    cuerpo = r.json()
+    assert cuerpo["error"] == "CsrfValidationError"
+    assert cuerpo["code"] == CODIGO_SESION_ANTERIOR
+    assert "sesión anterior" in cuerpo["detail"]
+
+
+def test_tambien_se_reconoce_un_token_de_dos_rotaciones_atras(client, contenedor):
+    _alta(client)
+    primero = _sign_in_cookie(client).headers[CSRF_HEADER]
+    assert client.post("/auth/refresh", headers=_csrf_headers(client)).status_code == 200
+    assert client.post("/auth/refresh", headers=_csrf_headers(client)).status_code == 200
+
+    r = _escribir(client, primero)
+
+    assert r.status_code == 403
+    assert r.json()["code"] == CODIGO_SESION_ANTERIOR
+
+
+def test_un_token_inventado_tiene_el_code_generico(client, contenedor):
+    _alta(client)
+    _sign_in_cookie(client)
+
+    r = _escribir(client, "x" * 43)
+
+    assert r.status_code == 403
+    cuerpo = r.json()
+    assert cuerpo["error"] == "CsrfValidationError"
+    assert cuerpo["code"] == CODIGO_INVALIDO
+    assert "sesión anterior" not in cuerpo["detail"]
+
+
+def test_un_token_inventado_tras_un_refresh_sigue_siendo_generico(client, contenedor):
+    """Que la sesión haya rotado no vuelve «de una sesión anterior» a cualquier valor."""
+    _alta(client)
+    _sign_in_cookie(client)
+    assert client.post("/auth/refresh", headers=_csrf_headers(client)).status_code == 200
+
+    r = _escribir(client, derive_csrf_token("00000000-0000-0000-0000-000000000000", CLAVE))
+
+    assert r.status_code == 403
+    assert r.json()["code"] == CODIGO_INVALIDO
+
+
+def test_el_token_de_otra_cuenta_es_generico_no_de_sesion_anterior(client, contenedor):
+    """Un token **válido** pero de otra familia no se reconoce como «de una sesión anterior»."""
+    ajeno = TestClient(client.app, raise_server_exceptions=False)
+    r = ajeno.post("/auth/sign-up", json={"email": "bea@test.com", "password": PASS})
+    assert r.status_code == 201, r.text
+    r = ajeno.post(
+        "/auth/verify-email",
+        json={"email": "bea@test.com", "code": r.json()["verification_code"]},
+    )
+    assert r.status_code == 200, r.text
+    token_ajeno = ajeno.post(
+        "/auth/sign-in",
+        json={"email": "bea@test.com", "password": PASS},
+        headers={"Origin": ORIGEN},
+    ).headers[CSRF_HEADER]
+
+    # El alta y el sign-in tienen un límite de 5 por IP que comparten las dos cuentas del test.
+    from hexcore.config import LazyConfig
+    from hexcore.infrastructure.cache.cache_backends.memory import MemoryCache
+
+    LazyConfig.get_config().cache_backend = MemoryCache()
+
+    _alta(client)
+    entrada = _sign_in_cookie(client)
+    assert entrada.status_code == 200, entrada.text
+    r = _escribir(client, token_ajeno)
+
+    assert r.status_code == 403
+    assert r.json()["code"] == CODIGO_INVALIDO
+
+
+def test_sin_el_header_el_rechazo_tiene_el_code_generico(client, contenedor):
+    _alta(client)
+    _sign_in_cookie(client)
+
+    r = _escribir(client, None)
+
+    assert r.status_code == 403
+    assert r.json()["code"] == CODIGO_INVALIDO
+
+
+def test_un_origen_ajeno_se_rechaza_sin_code(client, contenedor):
+    """No es un problema del token: no hay nada que recuperar pidiendo otro."""
+    _alta(client)
+    _sign_in_cookie(client)
+
+    r = client.post(
+        "/auth/sign-out",
+        headers={"Origin": "https://evil.test", CSRF_HEADER: client.cookies.get("csrf") or ""},
+    )
+
+    assert r.status_code == 403
+    assert "code" not in r.json()
+
+
+def test_un_repositorio_sin_listado_de_familia_cae_al_code_generico(client, contenedor):
+    """Un backend propio que no implementa el puerto nuevo no pierde el 403, sólo el `code`."""
+    _alta(client)
+    anterior = _sign_in_cookie(client).headers[CSRF_HEADER]
+    assert client.post("/auth/refresh", headers=_csrf_headers(client)).status_code == 200
+
+    from hexcore.darwin.domain.ports import AbstractSessionRepository
+
+    repo = contenedor.sessions_repository()
+    original = type(repo).list_family_session_ids
+    type(repo).list_family_session_ids = AbstractSessionRepository.list_family_session_ids
+    try:
+        r = _escribir(client, anterior)
+    finally:
+        type(repo).list_family_session_ids = original
+
+    assert r.status_code == 403
+    assert r.json()["code"] == CODIGO_INVALIDO
+
+
+def test_si_la_clasificacion_falla_el_rechazo_sigue_siendo_un_403(client, contenedor):
+    """La lectura de la base es accesoria: si revienta nunca se convierte en un 500."""
+    _alta(client)
+    anterior = _sign_in_cookie(client).headers[CSRF_HEADER]
+    assert client.post("/auth/refresh", headers=_csrf_headers(client)).status_code == 200
+
+    repo = contenedor.sessions_repository()
+    original = type(repo).list_family_session_ids
+
+    async def _explota(self, family_id, *, limit=100):
+        raise RuntimeError("la base no responde")
+
+    type(repo).list_family_session_ids = _explota
+    try:
+        r = _escribir(client, anterior)
+    finally:
+        type(repo).list_family_session_ids = original
+
+    assert r.status_code == 403
+    assert r.json()["code"] == CODIGO_INVALIDO
+
+
+def test_el_token_vigente_sigue_pasando_tras_la_rotacion(client, contenedor):
+    """La clasificación sólo corre al rechazar: el camino feliz no cambia."""
+    _alta(client)
+    _sign_in_cookie(client)
+    assert client.post("/auth/refresh", headers=_csrf_headers(client)).status_code == 200
+
+    r = _escribir(client, client.cookies.get("csrf"))
+
+    assert r.status_code == 200, r.text