hexcore 9.0.0__tar.gz → 9.2.1__tar.gz

{hexcore-9.0.0/hexcore.egg-info → hexcore-9.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hexcore
-Version: 9.0.0
+Version: 9.2.1
 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
@@ -335,6 +335,6 @@ There is a set of skills for extending HexCore in VS Code and compatible environ
 
 - [docs/](./docs/) — the complete documentation, in English and Spanish.
 - [docs/ARCHITECTURE_TYPING.md](./docs/ARCHITECTURE_TYPING.md) — type system and stubs.
-- [CHANGELOG.md](./CHANGELOG.md) — change history.
-- [CONTRIBUTING.md](./CONTRIBUTING.md) — collaboration guidelines.
-- [SECURITY.md](./SECURITY.md) — security policy.
+- [CHANGELOG.md](../../CHANGELOG.md) — change history.
+- [CONTRIBUTING.md](../../CONTRIBUTING.md) — collaboration guidelines.
+- [SECURITY.md](../../SECURITY.md) — security policy.

{hexcore-9.0.0 → hexcore-9.2.1}/README.md

@@ -260,6 +260,6 @@ There is a set of skills for extending HexCore in VS Code and compatible environ
 
 - [docs/](./docs/) — the complete documentation, in English and Spanish.
 - [docs/ARCHITECTURE_TYPING.md](./docs/ARCHITECTURE_TYPING.md) — type system and stubs.
-- [CHANGELOG.md](./CHANGELOG.md) — change history.
-- [CONTRIBUTING.md](./CONTRIBUTING.md) — collaboration guidelines.
-- [SECURITY.md](./SECURITY.md) — security policy.
+- [CHANGELOG.md](../../CHANGELOG.md) — change history.
+- [CONTRIBUTING.md](../../CONTRIBUTING.md) — collaboration guidelines.
+- [SECURITY.md](../../SECURITY.md) — security policy.

{hexcore-9.0.0 → hexcore-9.2.1}/hexcore/darwin/application/plugins.py

@@ -333,6 +333,18 @@ class PluginRegistry:
             acumulado.update(plugin.exception_status_map())
         return acumulado
 
+    def exception_payload(self, exc: Exception) -> dict[str, t.Any]:
+        """
+        El payload extra combinado que los plugins agregan al body de `exc`.
+
+        Espejo de `exception_status_map()`: el del último plugin gana, y `create_app`
+        mergea esto debajo del identity-level y del consumidor.
+        """
+        acumulado: dict[str, t.Any] = {}
+        for plugin in self.plugins:
+            acumulado.update(plugin.exception_payload(exc))
+        return acumulado
+
     def register_handlers(self, registry: t.Any) -> t.Any:
         for plugin in self.plugins:
             plugin.register_handlers(registry)

{hexcore-9.0.0 → hexcore-9.2.1}/hexcore/darwin/domain/plugins.py

@@ -237,6 +237,22 @@ class DarwinPlugin(abc.ABC):
         """
         return {}
 
+    def exception_payload(self, exc: Exception) -> t.Mapping[str, t.Any]:
+        """
+        Claves extra para el **cuerpo** de la excepción, si el plugin las tiene.
+
+        Espejo de `exception_status_map()` pero para el body en vez del status: hay
+        excepciones que llevan datos que el cliente necesita para completar el flujo — el
+        `challenge` de `TwoFactorRequiredError`, que el segundo paso del login exige de
+        vuelta en `POST /auth/2fa/challenge` — y que no caben en `detail` sin obligar al
+        cliente a parsear texto.
+
+        Método **concreto** que devuelve vacío, igual que el resto de los puntos de
+        extensión de `DarwinPlugin`: agregar éste no rompe a ningún plugin existente, que
+        no tiene por qué aportar nada al body de sus errores.
+        """
+        return {}
+
     def register_handlers(self, registry: t.Any) -> None:
         """
         Registra los comandos y queries del plugin en el `HandlerRegistry`.

{hexcore-9.0.0 → hexcore-9.2.1}/hexcore/darwin/infrastructure/api/dependencies.py

@@ -33,6 +33,7 @@ __all__ = [
     "require_roles",
     "require_not_impersonated",
     "identity_exception_headers",
+    "identity_exception_payload",
 ]
 
 #: El valor de `WWW-Authenticate` de un 401. RFC 6750 §3.
@@ -174,3 +175,27 @@ def identity_exception_headers(exc: Exception) -> t.Mapping[str, str]:
     if isinstance(exc, AuthenticationError):
         return {"WWW-Authenticate": WWW_AUTHENTICATE}
     return {}
+
+
+def identity_exception_payload(exc: Exception) -> t.Mapping[str, t.Any]:
+    """
+    El payload extra que las excepciones de identidad agregan al cuerpo del error.
+
+    Se pasa a `create_app(exception_payload=...)`, y `create_app` lo hace sólo cuando
+    `AppFeatures.auth_context` está prendido — mismo cableado que `identity_exception_headers`.
+
+    A diferencia de los headers —genéricos para toda `AuthenticationError`—, qué payload
+    corresponde es específico de cada plugin (el `challenge` de `TwoFactorRequiredError`, por
+    ejemplo), así que esta función delega en `PluginRegistry.exception_payload()` del
+    despliegue en curso en vez de chequear un tipo fijo.
+
+    Sin un despliegue configurado (`create_app` corrido antes de `configure_identity`, o sin
+    Darwin) devuelve vacío en vez de lanzar — mismo trato que `_mapa_de_plugins()` en `app.py`.
+    """
+    from hexcore.darwin.application.container import get_identity_container
+
+    try:
+        contenedor = get_identity_container()
+    except Exception:
+        return {}
+    return contenedor.plugins.exception_payload(exc)

{hexcore-9.0.0 → hexcore-9.2.1}/hexcore/darwin/infrastructure/api/routers.py

@@ -43,6 +43,9 @@ __all__ = [
     "SignInRequest",
     "SessionResponse",
     "MeResponse",
+    "SignedOutResponse",
+    "RevokedResponse",
+    "SessionInfo",
     "build_identity_router",
     "emit_tokens",
     "session_response_body",
@@ -100,6 +103,31 @@ class MeResponse(BaseModel):
     scopes: list[str] = Field(default_factory=list)
 
 
+class SignedOutResponse(BaseModel):
+    """La respuesta de `POST /auth/sign-out`."""
+
+    signed_out: bool
+
+
+class RevokedResponse(BaseModel):
+    """La respuesta de `POST /auth/sign-out-everywhere`: cuántas sesiones se revocaron."""
+
+    revoked: int
+
+
+class SessionInfo(BaseModel):
+    """Una fila de `GET /auth/sessions`, para una pantalla de seguridad."""
+
+    session_id: str
+    transport: str
+    created_at: str
+    expires_at: str
+    ip_address: str | None
+    user_agent: str | None
+    impersonated: bool
+    current: bool
+
+
 # ── Helpers de transporte ─────────────────────────────────────────────────────
 def resolve_transport(request: Request) -> "AbstractTransport":
     """Dependencia: el transporte de este request, resuelto una sola vez."""
@@ -241,7 +269,7 @@ def build_identity_router(
         usuario = await servicio.verify_email(email=payload.email, code=payload.code)
         return {"email_verified": usuario.email_verified}
 
-    @router.post("/sign-in", dependencies=limite)
+    @router.post("/sign-in", dependencies=limite, response_model=SessionResponse)
     async def sign_in(
         payload: SignInRequest,
         request: Request,
@@ -270,7 +298,7 @@ def build_identity_router(
         emit_tokens(respuesta, tokens, transport, contenedor.config)
         return respuesta
 
-    @router.post("/refresh")
+    @router.post("/refresh", response_model=SessionResponse)
     async def refresh(
         request: Request,
         transport: "AbstractTransport" = Depends(resolve_transport),
@@ -304,7 +332,7 @@ def build_identity_router(
         emit_tokens(respuesta, tokens, transport, contenedor.config)
         return respuesta
 
-    @router.post("/sign-out")
+    @router.post("/sign-out", response_model=SignedOutResponse)
     async def sign_out(
         auth: "AuthContext[t.Any]" = Depends(provide_auth),
         transport: "AbstractTransport" = Depends(resolve_transport),
@@ -335,6 +363,7 @@ def build_identity_router(
     @router.post(
         "/sign-out-everywhere",
         dependencies=[Depends(require_not_impersonated("sign_out_everywhere"))],
+        response_model=RevokedResponse,
     )
     async def sign_out_everywhere(
         auth: "AuthContext[t.Any]" = Depends(provide_auth),
@@ -386,10 +415,10 @@ def build_identity_router(
             scopes=sorted(auth.actor.scopes),
         )
 
-    @router.get("/sessions")
+    @router.get("/sessions", response_model=list[SessionInfo])
     async def sessions(
         auth: "AuthContext[t.Any]" = Depends(provide_auth),
-    ) -> list[dict[str, t.Any]]:
+    ) -> list[SessionInfo]:
         """
         Las sesiones vivas del sujeto, para una pantalla de seguridad.
 
@@ -402,16 +431,16 @@ def build_identity_router(
         repo = get_identity_container().sessions_repository()
         vivas = await repo.list_active_for_user(t.cast(t.Any, auth.subject_id))
         return [
-            {
-                "session_id": str(s.id),
-                "transport": s.transport,
-                "created_at": s.created_at.isoformat(),
-                "expires_at": s.expires_at.isoformat(),
-                "ip_address": s.ip_address,
-                "user_agent": s.user_agent,
-                "impersonated": s.is_impersonated,
-                "current": s.id == getattr(auth.actor, "session_id", None),
-            }
+            SessionInfo(
+                session_id=str(s.id),
+                transport=s.transport,
+                created_at=s.created_at.isoformat(),
+                expires_at=s.expires_at.isoformat(),
+                ip_address=s.ip_address,
+                user_agent=s.user_agent,
+                impersonated=s.is_impersonated,
+                current=s.id == getattr(auth.actor, "session_id", None),
+            )
             for s in vivas
         ]
 

{hexcore-9.0.0 → hexcore-9.2.1}/hexcore/darwin/plugins/impersonate/router.py

@@ -22,7 +22,15 @@ from fastapi import APIRouter, Depends, Request, Response
 from fastapi.responses import JSONResponse
 from pydantic import BaseModel, Field
 
-__all__ = ["StartImpersonationBody", "ImpersonationStatus", "build_impersonate_router"]
+from hexcore.darwin.infrastructure.api.routers import SessionResponse
+
+__all__ = [
+    "StartImpersonationBody",
+    "ImpersonationStatus",
+    "ImpersonationStoppedResponse",
+    "ImpersonationStartedResponse",
+    "build_impersonate_router",
+]
 
 
 class StartImpersonationBody(BaseModel):
@@ -44,6 +52,30 @@ class ImpersonationStatus(BaseModel):
     expires_at: str | None = None
 
 
+class ImpersonationStoppedResponse(BaseModel):
+    """La respuesta de `POST /auth/impersonate/stop`."""
+
+    stopped: bool
+
+
+class ImpersonationStartedResponse(SessionResponse):
+    """
+    La respuesta de `POST /auth/impersonate/{user_id}`.
+
+    `impersonating` queda **deprecado**: en esta ruta lleva el id del sujeto impersonado como
+    string, mientras que en `MeResponse.impersonating` es un `bool` — el mismo nombre significa
+    dos cosas distintas según la ruta, y un cliente TypeScript no puede tipar las dos con el
+    mismo campo sin mentir. Renombrarlo sería breaking y no lo amerita un major; en su lugar,
+    `subject_id` es el mismo valor con un nombre que no colisiona.
+    """
+
+    impersonating: str
+    subject_id: str
+    #: Cuándo vence la ventana de impersonación (no la del access token, que es
+    #: `expires_in`, heredado de `SessionResponse`).
+    expires_at: str | None = None
+
+
 def build_impersonate_router(
     *,
     prefix: str = "/auth/impersonate",
@@ -95,7 +127,7 @@ def build_impersonate_router(
     # registro, así que con `/{user_id}` primero, un `POST /auth/impersonate/stop` matchea la
     # ruta paramétrica e intenta parsear `"stop"` como UUID — 422 en vez de terminar la
     # impersonación. Lo encontró un test, no la revisión.
-    @router.post("/stop")
+    @router.post("/stop", response_model=ImpersonationStoppedResponse)
     async def stop(
         auth: t.Any = Depends(provide_auth),
         transport: t.Any = Depends(_resolve_transport),
@@ -114,7 +146,9 @@ def build_impersonate_router(
         transport.clear(respuesta)
         return respuesta
 
-    @router.post("/{user_id}", dependencies=limite)
+    @router.post(
+        "/{user_id}", dependencies=limite, response_model=ImpersonationStartedResponse
+    )
     async def start(
         user_id: UUID,
         payload: StartImpersonationBody,
@@ -149,6 +183,10 @@ def build_impersonate_router(
             exclude_none=True
         )
         cuerpo["impersonating"] = str(resultado.subject.id)
+        # `subject_id` es el mismo valor que `impersonating`, con un nombre que no colisiona
+        # con el `bool` de `MeResponse.impersonating`. Ver el docstring de
+        # `ImpersonationStartedResponse`.
+        cuerpo["subject_id"] = str(resultado.subject.id)
         cuerpo["expires_at"] = (
             resultado.session.impersonation_expires_at.isoformat()
             if resultado.session.impersonation_expires_at

{hexcore-9.0.0 → hexcore-9.2.1}/hexcore/darwin/plugins/magic_link/router.py

@@ -18,7 +18,14 @@ from fastapi import APIRouter, Depends, Request, Response
 from fastapi.responses import JSONResponse
 from pydantic import BaseModel
 
-__all__ = ["RequestMagicLinkBody", "ConsumeMagicLinkBody", "build_magic_link_router"]
+from hexcore.darwin.infrastructure.api.routers import SessionResponse
+
+__all__ = [
+    "RequestMagicLinkBody",
+    "ConsumeMagicLinkBody",
+    "MagicLinkRequested",
+    "build_magic_link_router",
+]
 
 
 class RequestMagicLinkBody(BaseModel):
@@ -30,6 +37,18 @@ class ConsumeMagicLinkBody(BaseModel):
     token: str
 
 
+class MagicLinkRequested(BaseModel):
+    """
+    La respuesta de `POST /auth/magic-link/request`.
+
+    `token` sólo viaja en un despliegue que no manda mails de verdad — ver la advertencia del
+    docstring de la ruta: en producción no se devuelve, y el campo queda `None`.
+    """
+
+    sent: bool
+    token: str | None = None
+
+
 def build_magic_link_router(
     *,
     prefix: str = "/auth/magic-link",
@@ -58,8 +77,18 @@ def build_magic_link_router(
     vida = ttl or DEFAULT_TTL
     limite = _rate_limit(rate_limit)
 
-    @router.post("/request", dependencies=limite)
-    async def request(payload: RequestMagicLinkBody) -> dict[str, t.Any]:
+    @router.post(
+        "/request",
+        dependencies=limite,
+        response_model=MagicLinkRequested,
+        # `exclude_none`: antes de este `response_model` la ruta devolvía un `dict` que
+        # directamente omitía la clave `token` cuando era `None`. Sin esto, el modelo la
+        # incluiría como `null` en los dos casos — no filtra nada (la ruta sigue
+        # respondiendo igual exista o no la cuenta), pero cambiaría el shape que un
+        # cliente ya integrado contra el dict viejo espera.
+        response_model_exclude_none=True,
+    )
+    async def request(payload: RequestMagicLinkBody) -> MagicLinkRequested:
         """
         Pide un magic link. **Responde igual exista o no la cuenta.**
 
@@ -74,12 +103,9 @@ def build_magic_link_router(
 
         # La forma de la respuesta es idéntica en los dos casos. Que el token venga o no es lo
         # único que cambia, y en producción no se devuelve.
-        cuerpo: dict[str, t.Any] = {"sent": True}
-        if emitido.token is not None:
-            cuerpo["token"] = emitido.token
-        return cuerpo
+        return MagicLinkRequested(sent=True, token=emitido.token)
 
-    @router.post("/consume")
+    @router.post("/consume", response_model=SessionResponse)
     async def consume(
         payload: ConsumeMagicLinkBody,
         request: Request,

{hexcore-9.0.0 → hexcore-9.2.1}/hexcore/darwin/plugins/oauth/router.py

@@ -25,9 +25,12 @@ from fastapi import APIRouter, Depends, Query, Request, Response
 from fastapi.responses import JSONResponse
 from pydantic import BaseModel
 
+from hexcore.darwin.infrastructure.api.routers import SessionResponse
+
 __all__ = [
     "AuthorizationResponse",
     "LinkedProviders",
+    "OAuthCallbackResponse",
     "build_oauth_router",
 ]
 
@@ -50,6 +53,17 @@ class LinkedProviders(BaseModel):
     providers: list[str]
 
 
+class OAuthCallbackResponse(SessionResponse):
+    """
+    La respuesta de `GET /auth/oauth/{provider}/callback`.
+
+    `created` distingue un signup implícito de un login: es lo que el cliente necesita para
+    mandar a un usuario nuevo a onboarding en vez de al home.
+    """
+
+    created: bool
+
+
 def build_oauth_router(
     *,
     prefix: str = "/auth/oauth",
@@ -84,7 +98,12 @@ def build_oauth_router(
 
         return LinkedProviders(providers=list(get_oauth_service().provider_ids))
 
-    @router.get("/{provider}/start", dependencies=limite)
+    @router.get(
+        "/{provider}/start",
+        dependencies=limite,
+        response_model=AuthorizationResponse,
+        responses={302: {"description": "Con `?redirect=1`: redirect directo al proveedor."}},
+    )
     async def start(
         provider: str,
         redirect_uri: str = Query(..., description="A dónde vuelve el usuario."),
@@ -110,7 +129,9 @@ def build_oauth_router(
             ).model_dump()
         )
 
-    @router.get("/{provider}/callback", dependencies=limite)
+    @router.get(
+        "/{provider}/callback", dependencies=limite, response_model=OAuthCallbackResponse
+    )
     async def callback(
         provider: str,
         request: Request,

{hexcore-9.0.0 → hexcore-9.2.1}/hexcore/darwin/plugins/organization/router.py

@@ -30,6 +30,7 @@ __all__ = [
     "OrganizationOut",
     "MemberOut",
     "InvitationOut",
+    "InvitationIssued",
     "build_organization_router",
 ]
 
@@ -87,11 +88,19 @@ class InvitationOut(BaseModel):
     """
 
     id: str
+
     email: str
     role: OrgRole
     expires_at: str
 
 
+class InvitationIssued(BaseModel):
+    """La respuesta de `POST /organizations/{organization_id}/invitations`."""
+
+    invitation: InvitationOut
+    token: str
+
+
 def build_organization_router(
     *,
     prefix: str = "/organizations",
@@ -240,12 +249,16 @@ def build_organization_router(
         return {"removed": True}
 
     # ── Las invitaciones ──────────────────────────────────────────────────────
-    @router.post("/{organization_id}/invitations", status_code=201)
+    @router.post(
+        "/{organization_id}/invitations",
+        status_code=201,
+        response_model=InvitationIssued,
+    )
     async def invitar(
         organization_id: UUID,
         payload: InviteBody,
         auth: t.Any = Depends(provide_auth),
-    ) -> dict[str, t.Any]:
+    ) -> InvitationIssued:
         """
         Invita a alguien. Requiere ser `admin` o más, y no se puede invitar por encima del rol
         propio.
@@ -262,10 +275,9 @@ def build_organization_router(
             email=payload.email,
             role=payload.role,
         )
-        return {
-            "invitation": _invitation_out(emitida.invitation).model_dump(),
-            "token": emitida.token,
-        }
+        return InvitationIssued(
+            invitation=_invitation_out(emitida.invitation), token=emitida.token
+        )
 
     @router.get("/{organization_id}/invitations")
     async def pendientes(

{hexcore-9.0.0 → hexcore-9.2.1}/hexcore/darwin/plugins/passkey/router.py

@@ -23,6 +23,8 @@ from fastapi import APIRouter, Depends, Request, Response
 from fastapi.responses import JSONResponse
 from pydantic import BaseModel, Field
 
+from hexcore.darwin.infrastructure.api.routers import SessionResponse
+
 __all__ = [
     "FinishRegistrationBody",
     "AuthenticationOptionsBody",
@@ -99,7 +101,20 @@ def build_passkey_router(
     limite = _rate_limit(rate_limit)
 
     # ── Registro (con sesión) ─────────────────────────────────────────────────
-    @router.post("/register/options")
+    # Sin `response_model`: la forma es la de `PublicKeyCredentialCreationOptions` del spec
+    # WebAuthn (https://www.w3.org/TR/webauthn-3/#dictionary-makecredentialoptions).
+    # Remodelarla en pydantic sería mantener una copia de un estándar ajeno para ganar un
+    # schema que un cliente ya escribe a mano contra el spec — `openapi_extra` documenta la
+    # referencia sin pagar esa copia.
+    @router.post(
+        "/register/options",
+        openapi_extra={
+            "externalDocs": {
+                "description": "PublicKeyCredentialCreationOptions (WebAuthn L3)",
+                "url": "https://www.w3.org/TR/webauthn-3/#dictionary-makecredentialoptions",
+            }
+        },
+    )
     async def register_options(
         auth: t.Any = Depends(provide_auth),
     ) -> dict[str, t.Any]:
@@ -140,7 +155,18 @@ def build_passkey_router(
         return _resumen(guardada)
 
     # ── Login (público) ───────────────────────────────────────────────────────
-    @router.post("/authenticate/options", dependencies=limite)
+    # Mismo motivo que `/register/options`: la forma es la de
+    # `PublicKeyCredentialRequestOptions` del spec WebAuthn.
+    @router.post(
+        "/authenticate/options",
+        dependencies=limite,
+        openapi_extra={
+            "externalDocs": {
+                "description": "PublicKeyCredentialRequestOptions (WebAuthn L3)",
+                "url": "https://www.w3.org/TR/webauthn-3/#dictionary-assertion-options",
+            }
+        },
+    )
     async def authenticate_options(
         payload: AuthenticationOptionsBody,
     ) -> dict[str, t.Any]:
@@ -166,7 +192,9 @@ def build_passkey_router(
         opciones = await get_passkey_service().start_authentication(user_id=user_id)
         return opciones.options
 
-    @router.post("/authenticate", dependencies=limite)
+    @router.post(
+        "/authenticate", dependencies=limite, response_model=SessionResponse
+    )
     async def authenticate(
         payload: FinishAuthenticationBody,
         request: Request,

{hexcore-9.0.0 → hexcore-9.2.1}/hexcore/darwin/plugins/two_factor/__init__.py

@@ -179,6 +179,18 @@ class TwoFactorPlugin(DarwinPlugin):
     def exception_status_map(self) -> t.Mapping[type[Exception], int]:
         return TWO_FACTOR_EXCEPTION_STATUS_MAP
 
+    def exception_payload(self, exc: Exception) -> t.Mapping[str, t.Any]:
+        """
+        El `challenge` de `TwoFactorRequiredError`, en el cuerpo del 401.
+
+        Sin esto el segundo paso del login no es completable desde HTTP: `POST
+        /auth/2fa/challenge` exige el `challenge` de vuelta, y hasta la Fase 0 el cliente
+        nunca lo recibía — sólo vivía en el atributo Python de la excepción.
+        """
+        if isinstance(exc, TwoFactorRequiredError) and exc.challenge is not None:
+            return {"challenge": exc.challenge}
+        return {}
+
     def hooks(self) -> t.Sequence[HookBinding]:
         from hexcore.darwin.application.services import SIGN_IN_AUTHENTICATED
 

{hexcore-9.0.0 → hexcore-9.2.1}/hexcore/darwin/plugins/two_factor/router.py

@@ -22,6 +22,8 @@ from fastapi import APIRouter, Depends, Request, Response
 from fastapi.responses import JSONResponse
 from pydantic import BaseModel
 
+from hexcore.darwin.infrastructure.api.routers import SessionResponse
+
 __all__ = [
     "ConfirmBody",
     "DisableBody",
@@ -156,7 +158,7 @@ def build_two_factor_router(
         )
         return {"disabled": True}
 
-    @router.post("/challenge", dependencies=limite)
+    @router.post("/challenge", dependencies=limite, response_model=SessionResponse)
     async def challenge(
         payload: ChallengeBody,
         request: Request,