hexcore 11.2.0__tar.gz → 11.3.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hexcore
-Version: 11.2.0
+Version: 11.3.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.2.0 → hexcore-11.3.0}/hexcore/config.py

@@ -78,6 +78,26 @@ class ServerConfig(BaseModel):
     allow_methods: list[str] = ["*"]
     allow_headers: list[str] = ["*"]
 
+    # CORS para una SPA en otro origen con la cookie de sesión. Los tres van con el prefijo
+    # `cors_` porque `max_age` y `expose_headers` a secas, en una config que también tiene
+    # cookies y TTLs, se leen como otra cosa.
+    #
+    # `cors_origin_predicate` cubre los orígenes que `allow_origins` no puede enumerar —un
+    # subdominio por tenant creado en caliente—, igual que
+    # `IdentityConfig.trusted_origin_predicate` hace con el CSRF. **Se suma** a `allow_origins`,
+    # no lo reemplaza. Es síncrono, recibe el origen tal cual llega en el header `Origin`
+    # (`"https://a.ejemplo.com"`) y si lanza se trata como «no confiable».
+    #
+    # `cors_expose_headers`: las cabeceras de la respuesta que el JS puede leer entre orígenes.
+    # Sin declararlas, el navegador sólo deja leer las «seguras» (`Content-Type`, etc.).
+    #
+    # `cors_max_age`: cuántos segundos el navegador cachea el preflight. Sin caché, toda
+    # escritura JSON con un header propio (`X-CSRF-Token`) cuesta un `OPTIONS` previo. 600 es el
+    # default de Starlette; Chrome topea en 7200.
+    cors_origin_predicate: t.Callable[[str], bool] | None = None
+    cors_expose_headers: list[str] = Field(default_factory=list)
+    cors_max_age: int = Field(default=600, ge=0)
+
     # caching
     cache_backend: ICache = (
         MemoryCache()
@@ -171,6 +191,9 @@ class ServerConfig(BaseModel):
         1. Si no pasaste `allow_origins`, se completa: en `debug` queda `["*"]` (comodidad
            de desarrollo, que era la intención original), y fuera de `debug` queda
            `["http://localhost:<port>"]`. Un valor explícito —incluso `[]`— se respeta.
+           **Con un `cors_origin_predicate` declarado queda `[]`**: el predicado es la lista, y
+           derivar `["*"]` bajaría `allow_credentials` a `False` en silencio y las cookies
+           dejarían de funcionar sin que nadie lo pidiera.
         2. **`"*"` con `allow_credentials=True` nunca es válido, y el invariante vale
            siempre, no sólo fuera de `debug`.** Es que `debug` viene en `True` por
            defecto, así que condicionarlo al entorno dejaba la combinación peligrosa
@@ -194,9 +217,12 @@ class ServerConfig(BaseModel):
         lo_pidio_el_usuario = "allow_origins" in self.model_fields_set
 
         if not lo_pidio_el_usuario and not self.allow_origins:
-            self.allow_origins = (
-                ["*"] if self.debug else [f"http://localhost:{self.port}"]
-            )
+            if self.cors_origin_predicate is not None:
+                self.allow_origins = []
+            else:
+                self.allow_origins = (
+                    ["*"] if self.debug else [f"http://localhost:{self.port}"]
+                )
 
         if "*" not in self.allow_origins or not self.allow_credentials:
             return self

{hexcore-11.2.0 → hexcore-11.3.0}/hexcore/darwin/infrastructure/api/routers.py

@@ -31,6 +31,7 @@ from hexcore.darwin.infrastructure.api.dependencies import (
     provide_auth,
     require_not_impersonated,
 )
+from hexcore.darwin.infrastructure.api.middlewares import CSRF_HEADER
 
 if t.TYPE_CHECKING:
     from hexcore.darwin.application.config import IdentityConfig
@@ -42,6 +43,7 @@ __all__ = [
     "VerifyEmailRequest",
     "SignInRequest",
     "SessionResponse",
+    "CsrfTokenResponse",
     "MeResponse",
     "SignedOutResponse",
     "RevokedResponse",
@@ -122,6 +124,17 @@ class SignInRequest(BaseModel):
         return t.cast(str, self.identifier or self.email or self.username)
 
 
+class CsrfTokenResponse(BaseModel):
+    """
+    La respuesta de `GET /auth/csrf`: el valor anti-CSRF de la sesión en curso.
+
+    Es el mismo que trae la cookie de CSRF —`HMAC(secreto, sid)`, ver `derive_csrf_token`— y
+    que las respuestas que la emiten repiten en la cabecera `X-CSRF-Token`.
+    """
+
+    csrf_token: str
+
+
 class SessionResponse(BaseModel):
     """
     La respuesta de un sign-in o un refresh.
@@ -212,6 +225,14 @@ def emit_tokens(
     a propósito: el cliente tiene que poder leerla para devolverla en el header
     `X-CSRF-Token`. Que sea legible es lo que obliga a que su valor sea derivado del `sid` y
     no aleatorio — ver `derive_csrf_token`.
+
+    **Además va en la cabecera de la respuesta** (`X-CSRF-Token`, la misma que el cliente
+    devuelve en cada escritura). Una SPA en otro origen que la API —`app.ejemplo.com` contra
+    `api.ejemplo.com`— no puede leer esa cookie con `document.cookie`, porque pertenece al host
+    de la API: sin la cabecera no tiene de dónde sacar el valor, y toda escritura responde 403 sin
+    que nada apunte a la causa. La cabecera es legible cross-origin sólo si el CORS la expone
+    (`create_app` lo hace cuando `AppFeatures(csrf=True)`), o sea que no se la regala a un origen
+    que el CORS no permite; y el valor no sirve sin la cookie de sesión que el navegador ya tiene.
     """
     transport.emit(response, tokens)
 
@@ -234,15 +255,17 @@ def emit_tokens(
     #
     # El valor es un HMAC del `sid`, así que es válido mientras viva la sesión: alinearlo con
     # el refresh es lo coherente, y es el mismo número que la cookie de refresh.
+    valor = derive_csrf_token(str(tokens.session_id), clave.get_secret_value())
     response.set_cookie(
         config.cookies.name_for("csrf"),
-        derive_csrf_token(str(tokens.session_id), clave.get_secret_value()),
+        valor,
         max_age=int(config.tokens.refresh_ttl.total_seconds()),
         httponly=False,
         secure=config.cookies.secure,
         samesite=config.cookies.same_site,
         path=config.cookies.path,
     )
+    response.headers[CSRF_HEADER] = valor
 
 
 def session_response_body(
@@ -464,6 +487,44 @@ def build_identity_router(
         transport.clear(respuesta)
         return respuesta
 
+    @router.get("/csrf", response_model=CsrfTokenResponse)
+    async def csrf(
+        response: Response,
+        auth: "AuthContext[t.Any]" = Depends(provide_auth),
+    ) -> CsrfTokenResponse:
+        """
+        El valor anti-CSRF de la sesión por cookie en curso.
+
+        Para el cliente que **no puede leer la cookie de CSRF**: una SPA en otro origen que la
+        API (`document.cookie` sólo ve las cookies de su propio host). Lo pide al abrir la
+        página con una sesión ya existente y lo guarda **en memoria** — nunca en
+        `localStorage`—; el sign-in y el refresh lo entregan además en la cabecera
+        `X-CSRF-Token`, así que sólo hace falta acá cuando la página se recarga.
+
+        Es seguro darlo: sólo un origen que el CORS permita puede leer la respuesta, y el valor
+        no sirve sin la cookie de sesión que el navegador ya tiene. Es `HMAC(secreto, sid)`, el
+        mismo cálculo que `emit_tokens`.
+
+        **401 sin sesión por cookie.** Un cliente Bearer no hace CSRF —adjunta su token a
+        propósito— y pedirlo es un error de uso, no algo que haya que contestar.
+        """
+        from hexcore.darwin.application.container import get_identity_container
+        from hexcore.darwin.domain.exceptions import UnauthenticatedError
+        from hexcore.darwin.infrastructure.hashing import derive_csrf_token
+
+        config = get_identity_container().config
+        session_id = getattr(auth.actor, "session_id", None)
+        if auth.transport != "cookie" or session_id is None or config.secret_key is None:
+            raise UnauthenticatedError(
+                "El token anti-CSRF sólo existe para una sesión por cookie: un cliente Bearer "
+                "no hace CSRF."
+            )
+
+        response.headers["Cache-Control"] = "no-store"
+        return CsrfTokenResponse(
+            csrf_token=derive_csrf_token(str(session_id), config.secret_key.get_secret_value())
+        )
+
     @router.get("/me", response_model=MeResponse)
     async def me(auth: "AuthContext[t.Any]" = Depends(provide_auth)) -> MeResponse:
         """

{hexcore-11.2.0 → hexcore-11.3.0}/hexcore/fastapi.py

@@ -37,6 +37,10 @@ _EXPORTS: dict[str, tuple[str, str]] = {
         "RequestIDMiddleware",
     ),
     "TimingMiddleware": ("hexcore.infrastructure.api.middlewares", "TimingMiddleware"),
+    "PredicateCORSMiddleware": (
+        "hexcore.infrastructure.api.middlewares",
+        "PredicateCORSMiddleware",
+    ),
     "RequestIDLogFilter": (
         "hexcore.infrastructure.api.middlewares",
         "RequestIDLogFilter",

{hexcore-11.2.0 → hexcore-11.3.0}/hexcore/fastapi.pyi

@@ -9,7 +9,7 @@
 #
 # Existe porque la fachada resuelve sus exports con `__getattr__` y declara
 # `__all__ = sorted(_EXPORTS)`: las dos son expresiones de runtime, así que sin este stub
-# los 48 símbolos de `hexcore.fastapi` tipan `Any`. El runtime no cambia — Python usa
+# los 49 símbolos de `hexcore.fastapi` tipan `Any`. El runtime no cambia — Python usa
 # el `.py` y el checker usa el `.pyi`, así que la carga perezosa se mantiene.
 
 
@@ -42,6 +42,7 @@ from hexcore.infrastructure.api.lifespan import ProcrastinateStep as Procrastina
 from hexcore.infrastructure.api.lifespan import SqlEngineStep as SqlEngineStep
 from hexcore.infrastructure.api.lifespan import StartupStep as StartupStep
 from hexcore.infrastructure.api.lifespan import build_lifespan as build_lifespan
+from hexcore.infrastructure.api.middlewares import PredicateCORSMiddleware as PredicateCORSMiddleware
 from hexcore.infrastructure.api.middlewares import RequestIDLogFilter as RequestIDLogFilter
 from hexcore.infrastructure.api.middlewares import RequestIDMiddleware as RequestIDMiddleware
 from hexcore.infrastructure.api.middlewares import TimingMiddleware as TimingMiddleware
@@ -74,6 +75,7 @@ __all__ = [
     "EventBusStep",
     "HealthReport",
     "HealthRoutes",
+    "PredicateCORSMiddleware",
     "Probe",
     "ProcrastinateStep",
     "RequestIDLogFilter",

{hexcore-11.2.0 → hexcore-11.3.0}/hexcore/infrastructure/api/app.py

@@ -16,7 +16,7 @@ from pydantic import BaseModel
 
 from .exception_handlers import HeadersFactory, PayloadFactory, register_exception_handlers
 from .health import Probe, ResponseFactory, register_health_routes
-from .middlewares import RequestIDMiddleware, TimingMiddleware
+from .middlewares import PredicateCORSMiddleware, RequestIDMiddleware, TimingMiddleware
 from .routing import MountableRouter, mount_routers
 
 __all__ = ["AppFeatures", "HealthRoutes", "create_app"]
@@ -139,14 +139,6 @@ def create_app(
     # Los middlewares de Starlette se ejecutan en orden inverso al de registro, así que
     # el request-id se añade último para que envuelva a todo lo demás y su ContextVar
     # esté disponible en el resto de la pila.
-    if resolved_features.cors:
-        app.add_middleware(
-            CORSMiddleware,
-            allow_origins=list(getattr(config, "allow_origins", ["*"])),
-            allow_credentials=bool(getattr(config, "allow_credentials", True)),
-            allow_methods=list(getattr(config, "allow_methods", ["*"])),
-            allow_headers=list(getattr(config, "allow_headers", ["*"])),
-        )
     if resolved_features.timing:
         app.add_middleware(TimingMiddleware)
 
@@ -164,6 +156,39 @@ def create_app(
 
         app.add_middleware(AuthContextMiddleware)
 
+    # El CORS va **después** de los de Darwin —o sea, por fuera de ellos— y antes del
+    # request-id. Un middleware sólo le agrega cabeceras a lo que responde por dentro de él:
+    # con el CORS más adentro que el CSRF, el 403 de un `POST` cross-origin sin token salía
+    # sin `Access-Control-Allow-Origin`, y el navegador lo convertía en un error de red opaco
+    # en vez de dejarle leer a la app *por qué* falló (y reintentar con un token nuevo). Y
+    # el preflight se contesta acá, antes de gastar la resolución de la credencial.
+    if resolved_features.cors:
+        expose_headers = list(getattr(config, "cors_expose_headers", []))
+        if resolved_features.csrf:
+            # Darwin entrega el token anti-CSRF también en esta cabecera (para la SPA en otro
+            # origen, que no puede leer la cookie): sin exponerla, el JS no la ve.
+            from hexcore.darwin.infrastructure.api.middlewares import CSRF_HEADER
+
+            if CSRF_HEADER.lower() not in (h.lower() for h in expose_headers):
+                expose_headers.append(CSRF_HEADER)
+        cors_kwargs: dict[str, t.Any] = {
+            "allow_origins": list(getattr(config, "allow_origins", ["*"])),
+            "allow_credentials": bool(getattr(config, "allow_credentials", True)),
+            "allow_methods": list(getattr(config, "allow_methods", ["*"])),
+            "allow_headers": list(getattr(config, "allow_headers", ["*"])),
+            "expose_headers": expose_headers,
+            "max_age": int(getattr(config, "cors_max_age", 600)),
+        }
+        origin_predicate = getattr(config, "cors_origin_predicate", None)
+        if origin_predicate is None:
+            # Sin predicado, la clase es la de Starlette tal cual: nada cambia para quien no
+            # lo pide.
+            app.add_middleware(CORSMiddleware, **cors_kwargs)
+        else:
+            app.add_middleware(
+                PredicateCORSMiddleware, origin_predicate=origin_predicate, **cors_kwargs
+            )
+
     if resolved_features.request_id:
         app.add_middleware(RequestIDMiddleware)
 

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

@@ -15,12 +15,16 @@ import uuid
 import warnings
 from contextvars import ContextVar
 
+from starlette.datastructures import Headers, MutableHeaders
 from starlette.middleware.base import BaseHTTPMiddleware, RequestResponseEndpoint
+from starlette.middleware.cors import CORSMiddleware
 from starlette.requests import Request
 from starlette.responses import Response
+from starlette.types import Message, Receive, Scope, Send
 
 __all__ = [
     "REQUEST_ID",
+    "PredicateCORSMiddleware",
     "RequestIDMiddleware",
     "TimingMiddleware",
     "RequestIDLogFilter",
@@ -102,6 +106,66 @@ class TimingMiddleware(BaseHTTPMiddleware):
         return response
 
 
+cors_logger = logging.getLogger("hexcore.api.cors")
+
+
+class PredicateCORSMiddleware(CORSMiddleware):
+    """
+    `CORSMiddleware` que además acepta los orígenes que un predicado apruebe.
+
+    `allow_origins` es una lista fija, y un subdominio por tenant creado en caliente no se puede
+    enumerar de antemano: sin esto hay que redesplegar por cada alta, o abrir `"*"` — que con
+    credenciales no es válido. El predicado se consulta **sólo** cuando el origen no está ya en
+    la lista, así que declarar los dos no duplica trabajo.
+
+    Dos decisiones que no son obvias:
+
+    * **Falla cerrado.** Un predicado que lanza se trata como «no confiable» y se loguea en
+      `hexcore.api.cors`: un chequeo de confianza que explota nunca decide «confío» por default.
+      El log importa porque el síntoma —un origen legítimo sin CORS— no apunta a ninguna causa.
+    * **`Vary: Origin` siempre.** Con orígenes dinámicos la respuesta depende del `Origin`
+      también cuando se rechaza; sin `Vary`, una caché compartida podría servirle a un origen
+      aceptado la respuesta que guardó sin `Access-Control-Allow-Origin`. Starlette sólo lo
+      agrega cuando el origen es aceptado.
+    """
+
+    def __init__(
+        self,
+        app: t.Any,
+        *,
+        origin_predicate: t.Callable[[str], bool],
+        **kwargs: t.Any,
+    ) -> None:
+        super().__init__(app, **kwargs)
+        self._origin_predicate = origin_predicate
+
+    def is_allowed_origin(self, origin: str) -> bool:
+        if super().is_allowed_origin(origin):
+            return True
+        try:
+            return bool(self._origin_predicate(origin))
+        except Exception:
+            cors_logger.exception(
+                "cors_origin_predicate lanzó evaluando el origen %r; se lo trata como no "
+                "confiable.",
+                origin,
+            )
+            return False
+
+    async def simple_response(
+        self, scope: Scope, receive: Receive, send: Send, request_headers: Headers
+    ) -> None:
+        async def con_vary(message: Message) -> None:
+            if message["type"] == "http.response.start":
+                message.setdefault("headers", [])
+                headers = MutableHeaders(scope=message)
+                if "origin" not in headers.get("vary", "").lower():
+                    headers.add_vary_header("Origin")
+            await send(message)
+
+        await super().simple_response(scope, receive, con_vary, request_headers)
+
+
 class RequestIDLogFilter(logging.Filter):
     """
     Inyecta el request-id en cada `LogRecord` como ``record.request_id``.

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hexcore
-Version: 11.2.0
+Version: 11.3.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.2.0 → hexcore-11.3.0}/hexcore.egg-info/SOURCES.txt

@@ -290,6 +290,7 @@ hexcore/testing/repositories.py
 tests/test_alembic_metadata_completeness.py
 tests/test_anclas_del_repo.py
 tests/test_api_app_and_lifespan.py
+tests/test_api_cors_dinamico.py
 tests/test_api_cqrs_providers.py
 tests/test_api_exception_handlers.py
 tests/test_api_health.py

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

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

hexcore-11.3.0/tests/test_api_cors_dinamico.py

@@ -0,0 +1,250 @@
+"""
+CORS de `create_app`: por fuera de la auth y del CSRF, y con orígenes que no se enumeran.
+
+Dos problemas del mismo caso de uso —una SPA en otro origen que le habla a la API con la cookie
+de sesión—, y los dos fallan **en silencio**:
+
+1. `create_app` registraba el CORS **primero**, o sea que quedaba *por dentro* de
+   `AuthContextMiddleware` y de `CsrfMiddleware`. Un 403 de CSRF salía sin
+   `Access-Control-Allow-Origin` y el navegador lo convertía en un error de red opaco: la app
+   no podía leer *por qué* falló (ni reintentar con un token nuevo). El orden se prueba acá; que
+   el 403 real lleve las cabeceras, en `test_darwin_http.py`.
+2. `allow_origins` es una lista fija. Con un subdominio por tenant creado en caliente hay que
+   redesplegar por cada alta, o abrir `"*"` —que con credenciales no es válido—. Un
+   `cors_origin_predicate` cubre lo que la lista no enumera, igual que
+   `IdentityConfig.trusted_origin_predicate` hace con el CSRF.
+
+Además, sin `cors_max_age` cada escritura JSON con un header propio (`X-CSRF-Token`) cuesta un
+`OPTIONS` previo sin caché, y sin `cors_expose_headers` el JS no puede leer las cabeceras de la
+respuesta que la app le quiere entregar.
+"""
+from __future__ import annotations
+
+import logging
+import warnings
+
+import pytest
+
+pytest.importorskip("fastapi")
+pytest.importorskip("httpx")
+
+from fastapi.testclient import TestClient  # noqa: E402
+from pydantic import ValidationError  # noqa: E402
+from starlette.middleware.cors import CORSMiddleware  # noqa: E402
+
+from hexcore.config import ServerConfig  # noqa: E402
+from hexcore.fastapi import AppFeatures, create_app  # noqa: E402
+from hexcore.infrastructure.api.middlewares import PredicateCORSMiddleware  # noqa: E402
+
+TENANT = "https://a.tenant.test"
+AJENO = "https://evil.example"
+
+
+def _es_de_un_tenant(origen: str) -> bool:
+    return origen.endswith(".tenant.test")
+
+
+def _app(monkeypatch: pytest.MonkeyPatch, **campos):
+    """Una app con una `ServerConfig` propia (el `_config()` de `create_app` apunta a ella)."""
+    config = ServerConfig(**campos)
+    monkeypatch.setattr("hexcore.infrastructure.api.app._config", lambda: config)
+    return create_app(), config
+
+
+def _nombres(app) -> list[str]:
+    """De **afuera hacia adentro**: `user_middleware[0]` es el primero que ve el request."""
+    return [m.cls.__name__ for m in app.user_middleware]
+
+
+# ── 1. Orden ───────────────────────────────────────────────────────────────────
+def test_el_cors_envuelve_a_la_auth_y_al_csrf(monkeypatch):
+    """
+    Un middleware de Starlette sólo puede agregarle cabeceras a lo que responde **por dentro**
+    de él. Si el CORS está adentro del CSRF, el 403 del CSRF no las lleva.
+    """
+    config = ServerConfig(allow_origins=[TENANT])
+    monkeypatch.setattr("hexcore.infrastructure.api.app._config", lambda: config)
+
+    app = create_app(features=AppFeatures(auth_context=True, csrf=True))
+    nombres = _nombres(app)
+
+    assert nombres.index("CORSMiddleware") < nombres.index("AuthContextMiddleware")
+    assert nombres.index("CORSMiddleware") < nombres.index("CsrfMiddleware")
+
+
+def test_el_request_id_sigue_siendo_el_mas_externo(monkeypatch):
+    """
+    El request-id envuelve a todo lo demás para que su `ContextVar` esté disponible en la pila
+    entera, y el 403 del CSRF —que ahora sale por dentro del CORS— lo sigue llevando.
+    """
+    config = ServerConfig(allow_origins=[TENANT])
+    monkeypatch.setattr("hexcore.infrastructure.api.app._config", lambda: config)
+
+    app = create_app(features=AppFeatures(auth_context=True, csrf=True))
+
+    assert _nombres(app)[0] == "RequestIDMiddleware"
+
+
+def test_sin_predicado_el_middleware_es_el_de_starlette_tal_cual(monkeypatch):
+    """Quien no pide un predicado no cambia de clase: el comportamiento es el de siempre."""
+    app, _ = _app(monkeypatch, allow_origins=[TENANT])
+
+    clases = [m.cls for m in app.user_middleware]
+
+    assert CORSMiddleware in clases
+    assert PredicateCORSMiddleware not in clases
+
+
+# ── 2. cors_origin_predicate ───────────────────────────────────────────────────
+def test_un_origen_que_el_predicado_acepta_recibe_cors_con_credenciales(monkeypatch):
+    app, _ = _app(monkeypatch, allow_origins=[], cors_origin_predicate=_es_de_un_tenant)
+
+    with TestClient(app) as client:
+        r = client.get("/health", headers={"Origin": TENANT})
+
+    assert r.headers["access-control-allow-origin"] == TENANT
+    assert r.headers["access-control-allow-credentials"] == "true"
+
+
+def test_un_origen_que_el_predicado_rechaza_no_recibe_cors(monkeypatch):
+    app, _ = _app(monkeypatch, allow_origins=[], cors_origin_predicate=_es_de_un_tenant)
+
+    with TestClient(app) as client:
+        r = client.get("/health", headers={"Origin": AJENO})
+
+    assert "access-control-allow-origin" not in r.headers
+
+
+def test_el_preflight_de_un_origen_aceptado_pasa_y_el_de_uno_rechazado_no(monkeypatch):
+    app, _ = _app(monkeypatch, allow_origins=[], cors_origin_predicate=_es_de_un_tenant)
+    pedido = {
+        "Access-Control-Request-Method": "POST",
+        "Access-Control-Request-Headers": "content-type, x-csrf-token",
+    }
+
+    with TestClient(app) as client:
+        bueno = client.options("/health", headers={"Origin": TENANT, **pedido})
+        malo = client.options("/health", headers={"Origin": AJENO, **pedido})
+
+    assert bueno.status_code == 200
+    assert bueno.headers["access-control-allow-origin"] == TENANT
+    assert malo.status_code == 400
+    assert "access-control-allow-origin" not in malo.headers
+
+
+def test_la_lista_fija_y_el_predicado_se_suman(monkeypatch):
+    """La lista sigue mandando para lo que enumera; el predicado cubre el resto."""
+    fijo = "https://portal.example"
+    app, _ = _app(monkeypatch, allow_origins=[fijo], cors_origin_predicate=_es_de_un_tenant)
+
+    with TestClient(app) as client:
+        de_la_lista = client.get("/health", headers={"Origin": fijo})
+        del_predicado = client.get("/health", headers={"Origin": TENANT})
+        ajeno = client.get("/health", headers={"Origin": AJENO})
+
+    assert de_la_lista.headers["access-control-allow-origin"] == fijo
+    assert del_predicado.headers["access-control-allow-origin"] == TENANT
+    assert "access-control-allow-origin" not in ajeno.headers
+
+
+def test_un_predicado_que_lanza_se_trata_como_no_confiable(monkeypatch, caplog):
+    """
+    Falla cerrado, igual que `trusted_origin_predicate` y que un `AuthorizationProvider` que
+    revienta: un chequeo de confianza que explota nunca decide «confío» por default. Y se
+    loguea, porque el síntoma —un origen legítimo sin CORS— si no, no se diagnostica.
+    """
+
+    def explota(origen: str) -> bool:
+        raise RuntimeError("la base de tenants no responde")
+
+    app, _ = _app(monkeypatch, allow_origins=[], cors_origin_predicate=explota)
+
+    with caplog.at_level(logging.ERROR, logger="hexcore.api.cors"):
+        with TestClient(app) as client:
+            r = client.get("/health", headers={"Origin": TENANT})
+
+    assert r.status_code == 200
+    assert "access-control-allow-origin" not in r.headers
+    assert any("cors_origin_predicate" in m for m in caplog.messages)
+
+
+def test_la_respuesta_a_un_origen_rechazado_igual_declara_vary_origin(monkeypatch):
+    """
+    Con orígenes dinámicos la respuesta depende del `Origin` **también cuando se rechaza**. Sin
+    `Vary: Origin`, una caché compartida podría servirle a un origen aceptado la respuesta que
+    guardó sin `Access-Control-Allow-Origin`.
+    """
+    app, _ = _app(monkeypatch, allow_origins=[], cors_origin_predicate=_es_de_un_tenant)
+
+    with TestClient(app) as client:
+        r = client.get("/health", headers={"Origin": AJENO})
+
+    assert "Origin" in r.headers["vary"]
+
+
+def test_con_predicado_y_sin_allow_origins_no_se_deriva_el_comodin(monkeypatch):
+    """
+    El default de `allow_origins` en `debug` es `["*"]`, y con credenciales eso **baja
+    `allow_credentials` a `False` en silencio** (con un warning). Con un predicado declarado, el
+    predicado es la lista: derivar `["*"]` apagaría las cookies sin que nadie lo pidiera.
+    """
+    with warnings.catch_warnings(record=True) as avisos:
+        warnings.simplefilter("always")
+        config = ServerConfig(cors_origin_predicate=_es_de_un_tenant)
+
+    assert config.allow_origins == []
+    assert config.allow_credentials is True
+    assert not [a for a in avisos if "allow_credentials" in str(a.message)]
+
+
+def test_un_comodin_explicito_sigue_bajando_las_credenciales():
+    """Lo que ya no era válido sigue sin serlo: el predicado no relaja esa regla."""
+    with pytest.warns(UserWarning, match="allow_credentials"):
+        config = ServerConfig(allow_origins=["*"], cors_origin_predicate=_es_de_un_tenant)
+
+    assert config.allow_credentials is False
+
+
+# ── 3. cors_max_age y cors_expose_headers ──────────────────────────────────────
+def test_cors_max_age_llega_al_preflight(monkeypatch):
+    app, _ = _app(monkeypatch, allow_origins=[TENANT], cors_max_age=7200)
+
+    with TestClient(app) as client:
+        r = client.options(
+            "/health",
+            headers={"Origin": TENANT, "Access-Control-Request-Method": "POST"},
+        )
+
+    assert r.headers["access-control-max-age"] == "7200"
+
+
+def test_el_max_age_por_defecto_es_el_de_starlette(monkeypatch):
+    """Quien no lo declara no ve cambiar nada: 600 s, el default de `CORSMiddleware`."""
+    app, config = _app(monkeypatch, allow_origins=[TENANT])
+
+    with TestClient(app) as client:
+        r = client.options(
+            "/health",
+            headers={"Origin": TENANT, "Access-Control-Request-Method": "GET"},
+        )
+
+    assert config.cors_max_age == 600
+    assert r.headers["access-control-max-age"] == "600"
+
+
+def test_un_max_age_negativo_no_es_valido():
+    with pytest.raises(ValidationError):
+        ServerConfig(cors_max_age=-1)
+
+
+def test_cors_expose_headers_se_declara_en_la_respuesta(monkeypatch):
+    app, _ = _app(
+        monkeypatch,
+        allow_origins=[TENANT],
+        cors_expose_headers=["X-Request-ID", "Retry-After"],
+    )
+
+    with TestClient(app) as client:
+        r = client.get("/health", headers={"Origin": TENANT})
+
+    assert r.headers["access-control-expose-headers"] == "X-Request-ID, Retry-After"