openshell-shared 0.1.4__tar.gz → 0.1.5__tar.gz

{openshell_shared-0.1.4 → openshell_shared-0.1.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: openshell-shared
-Version: 0.1.4
+Version: 0.1.5
 Summary: Shared library for OpenShell (OSAM/OSA/OSAC)
 Author: Specter
 License: Proprietary

openshell_shared-0.1.5/openshell_shared/__init__.py

@@ -0,0 +1,7 @@
+from . import api
+from . import cryptography
+from . import domain
+from . import identity
+from . import modules
+from . import protocols
+from . import standards

openshell_shared-0.1.5/openshell_shared/api/__init__.py

@@ -0,0 +1 @@
+from . import manager

openshell_shared-0.1.5/openshell_shared/api/manager/__init__.py

@@ -0,0 +1 @@
+from . import v1

openshell_shared-0.1.5/openshell_shared/api/manager/v1/__init__.py

@@ -0,0 +1,78 @@
+# shared/api/manager/v1/__init__.py
+"""
+SDK oficial de Python para consumir la API HTTP de OpenShell Access
+Manager (OSAM).
+
+Uso típico::
+
+    from shared.api.manager.v1 import OSAMClient
+
+    async with OSAMClient(host="...", port=8000, protocol="https") as client:
+        ...
+
+Todo el sistema (OpenShell Console, OpenShell Agent, GUIs, herramientas
+automatizadas) debe consumir OSAM exclusivamente a través de este paquete;
+ningún otro componente debe importar ``httpx``/``requests`` directamente
+para hablar con OSAM.
+"""
+
+from .client import OSAMClient
+from .exceptions import (
+    APIError,
+    AuthenticationError,
+    AuthorizationError,
+    EntityNotFoundError,
+    InvalidResponseError,
+    NetworkError,
+    OSAMError,
+    ServerError,
+    ValidationError,
+)
+from .models import (
+    ClientChallenge,
+    ClientChallengeVerification,
+    CryptographicIdentity,
+    Domain,
+    Entity,
+    EntityTypeInfo,
+    IntegrationResult,
+    LogicalIdentity,
+    Passport,
+    ServerChallengeResponse,
+    SessionDeletionResult,
+    SessionInfo,
+    TunnelInfo,
+    TunnelOperationResult,
+)
+
+__all__ = [
+    # Cliente principal
+    "OSAMClient",
+    # Excepciones
+    "OSAMError",
+    "NetworkError",
+    "InvalidResponseError",
+    "APIError",
+    "ValidationError",
+    "AuthenticationError",
+    "AuthorizationError",
+    "EntityNotFoundError",
+    "ServerError",
+    # Modelos
+    "LogicalIdentity",
+    "CryptographicIdentity",
+    "EntityTypeInfo",
+    "ClientChallenge",
+    "ClientChallengeVerification",
+    "ServerChallengeResponse",
+    "Domain",
+    "Entity",
+    "Passport",
+    "IntegrationResult",
+    "SessionInfo",
+    "SessionDeletionResult",
+    "TunnelInfo",
+    "TunnelOperationResult",
+]
+
+__version__ = "0.1.0"

openshell_shared-0.1.5/openshell_shared/api/manager/v1/authentication.py

@@ -0,0 +1,278 @@
+# shared/api/manager/v1/authentication.py
+"""
+Dominio: Authentication.
+
+Implementa el protocolo de autenticación por challenge-response (Ed25519)
+de OSAM, en sus dos direcciones:
+
+* Autenticación del **cliente** ante el servidor (``client/challenge`` +
+  ``verify``): la entidad que llama solicita un reto, lo firma con su clave
+  privada y envía la respuesta para que el servidor la valide.
+* Autenticación del **servidor** ante el cliente (``server/challenge``):
+  el cliente ya posee un ``challenge_id`` (generado en un paso anterior del
+  protocolo, fuera del alcance de este módulo) y le pide al servidor que
+  produzca su respuesta firmada para poder verificarla localmente.
+
+Endpoints cubiertos (todos bajo ``/api/v/1/auth``):
+    POST /client/challenge
+    POST /verify
+    POST /server/challenge
+"""
+
+from __future__ import annotations
+
+from .models import (
+    ClientChallenge,
+    ClientChallengeVerification,
+    ServerChallengeResponse,
+)
+from .transport import HttpTransport
+from ....protocols.negotiation.challenge import ChallengeProtocol, CHALLENGE_TYPE_SERVER_AUTHENTICATION
+
+_PREFIX = "/api/v/1/auth"
+
+
+class AuthenticationAPI:
+    """API especializada para el protocolo de autenticación de OSAM."""
+
+    def __init__(self, transport: HttpTransport) -> None:
+        self._transport = transport
+
+    async def create_client_challenge(
+        self, entity_uid: str, public_key: str
+    ) -> dict:
+        """
+        POST /api/v/1/auth/client/challenge
+
+        Solicita al servidor un reto de autenticación para la entidad
+        identificada por ``entity_uid`` / ``public_key``.
+        """
+        body = await self._transport.post(
+            f"{_PREFIX}/client/challenge",
+            json={"entity_uid": entity_uid, "public_key": public_key},
+        )
+
+        return ClientChallenge.from_dict(body)
+
+    async def verify_client_challenge(
+        self,
+        challenge_id: str,
+        response: str,
+        entity_uid: str,
+        public_key: str,
+    ) -> ClientChallengeVerification:
+        """
+        POST /api/v/1/auth/verify
+
+        Envía la respuesta firmada a un reto previamente emitido por
+        ``create_client_challenge`` para completar la autenticación.
+        """
+        body = await self._transport.post(
+            f"{_PREFIX}/verify",
+            json={
+                "challenge_id": challenge_id,
+                "response": response,
+                "entity_uid": entity_uid,
+                "public_key": public_key,
+            },
+        )
+        return body
+
+    async def authenticate_client(self,
+        entity_uid: str,
+        entity_pik: str,
+        entity_ppik: str
+    ) -> str:
+        # Create challenge
+        client_challenge = await self.create_client_challenge(
+            entity_uid=entity_uid,
+            public_key=entity_pik
+        )
+
+        client_challenge_object = ChallengeProtocol.challenge_from_dict(
+            client_challenge.challenge
+        )
+
+        client_auth_signed = ChallengeProtocol.sign(
+            private_key=entity_ppik,
+            challenge=client_challenge_object
+        )
+
+        response = await self.verify_client_challenge(
+            challenge_id=client_challenge.challenge.get("challenge_id"),
+            response=ChallengeProtocol.response_to_dict(client_auth_signed),
+            entity_uid=entity_uid,
+            public_key=entity_pik
+        )
+
+        return response
+
+    # =====================================================
+    # SERVER AUTHENTICATION
+    # =====================================================
+
+    async def register_server_challenge(
+        self,
+        challenge: dict
+    ) -> dict:
+        """
+        Register challenge in remote server.
+
+        Client -> Server
+
+        POST:
+        /api/v/1/auth/server/challenge/register
+        """
+
+        body = await self._transport.post(
+            f"{_PREFIX}/server/challenge/register",
+            json={
+                "challenge": challenge
+            }
+        )
+
+        return body
+
+
+
+    async def request_server_response(
+        self,
+        challenge_id: str
+    ) -> dict:
+        """
+        Request signed challenge response.
+
+        Client -> Server
+
+        POST:
+        /api/v/1/auth/server/challenge/response
+        """
+
+        body = await self._transport.post(
+            f"{_PREFIX}/server/challenge/response",
+            json={
+                "challenge_id": challenge_id
+            }
+        )
+
+        return body
+
+
+
+    def verify_server_response(
+        self,
+        challenge: dict,
+        response: dict,
+        server_public_key: str
+    ) -> bool:
+        """
+        Verify server signature locally.
+        """
+
+
+        challenge_object = (
+            ChallengeProtocol.challenge_from_dict(
+                challenge
+            )
+        )
+
+
+        if not ChallengeProtocol.validate_type(
+            challenge_object,
+            CHALLENGE_TYPE_SERVER_AUTHENTICATION
+        ):
+
+            raise ValueError(
+                "Invalid server challenge type"
+            )
+
+
+        response_object = (
+            ChallengeProtocol.response_from_dict(
+                response["response"]
+            )
+        )
+
+
+        return ChallengeProtocol.verify(
+            public_key=server_public_key,
+            challenge=challenge_object,
+            response=response_object
+        )
+
+
+
+    async def authenticate_server(
+        self,
+        client_uid: str,
+        server_uid: str,
+        server_public_key: str
+    ) -> bool:
+        """
+        Authenticate remote server.
+        """
+
+
+        # -----------------------------------------
+        # 1. Create challenge
+        # -----------------------------------------
+
+        challenge = ChallengeProtocol.create(
+            challenge_type=(
+                CHALLENGE_TYPE_SERVER_AUTHENTICATION
+            ),
+
+            issuer_uid=client_uid,
+
+            target_uid=server_uid
+        )
+
+
+        challenge_dict = (
+            ChallengeProtocol.challenge_to_dict(
+                challenge
+            )
+        )
+
+
+        # -----------------------------------------
+        # 2. Register challenge remotely
+        # -----------------------------------------
+
+        await self.register_server_challenge(
+            challenge_dict
+        )
+
+
+        # -----------------------------------------
+        # 3. Ask server signature
+        # -----------------------------------------
+
+        response = await self.request_server_response(
+            challenge_dict["challenge_id"]
+        )
+
+
+        # -----------------------------------------
+        # 4. Verify server proof
+        # -----------------------------------------
+
+        verified = (
+            self.verify_server_response(
+                challenge=challenge_dict,
+
+                response=response,
+
+                server_public_key=server_public_key
+            )
+        )
+
+
+        if not verified:
+
+            raise ValueError(
+                "Server authentication failed"
+            )
+
+
+        return True

openshell_shared-0.1.5/openshell_shared/api/manager/v1/client.py

@@ -0,0 +1,111 @@
+# shared/api/manager/v1/client.py
+"""
+Cliente principal de la SDK de OSAM.
+
+``OSAMClient`` es el único punto de entrada que el resto del sistema
+(OpenShell Console, OpenShell Agent, futuras GUIs, herramientas
+automatizadas) debe usar para hablar con la API HTTP de OSAM. Internamente
+compone una única instancia de ``HttpTransport`` (la capa HTTP real) y la
+inyecta en cada API de dominio especializada.
+
+No hay estado global ni singletons: cada instancia de ``OSAMClient``
+representa una conexión independiente a un host:puerto concreto, y puede
+crearse tantas veces como se necesite (por ejemplo, una Console que habla
+simultáneamente con el Manager y, en el futuro, con un Agent expuesto en
+otro host).
+
+Ejemplo de uso::
+
+    import asyncio
+    from shared.api.manager.v1 import OSAMClient
+
+    async def main():
+        async with OSAMClient(host="fortaprest.org", port=8000, protocol="https") as client:
+            identity = await client.identity.get_logical_identity()
+            print(identity.uid)
+
+    asyncio.run(main())
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Union
+
+from .authentication import AuthenticationAPI
+from .domains import DomainsAPI
+from .entities import EntitiesAPI
+from .identity import IdentityAPI
+from .passports import PassportsAPI
+from .sessions import SessionsAPI
+from .transport import HttpTransport
+from .tunnels import TunnelsAPI
+
+logger = logging.getLogger("osam.client")
+
+_VALID_PROTOCOLS = ("http", "https")
+
+
+class OSAMClient:
+    """
+    Cliente de alto nivel para la API HTTP de OSAM.
+
+    Args:
+        host: Host o IP del servidor OSAM (Manager, normalmente).
+        port: Puerto HTTP/HTTPS de la API.
+        protocol: ``"http"`` o ``"https"``. Use ``"https"`` en producción;
+            el endurecimiento TLS del proyecto vive en el lado del servidor
+            (ver variables ``OSAM_MANAGER_HOST`` / ``OSAM_CA_BUNDLE``), esta
+            SDK solo necesita saber qué esquema usar y, opcionalmente, qué
+            bundle de CA validar contra él.
+        timeout: Timeout en segundos aplicado a cada petición HTTP.
+        verify_ssl: ``True``/``False`` para activar/desactivar la
+            verificación TLS, o una ruta a un bundle de CA personalizado
+            (equivalente al parámetro ``verify`` de ``httpx``). Útil para
+            apuntar a ``OSAM_CA_BUNDLE`` durante el endurecimiento HTTPS.
+
+    Atributos expuestos (una instancia por dominio funcional):
+        identity, authentication, domains, tunnels, sessions, passports,
+        entities.
+    """
+
+    def __init__(
+        self,
+        host: str,
+        port: int,
+        protocol: str = "http",
+        *,
+        timeout: float = 10.0,
+        verify_ssl: Union[bool, str] = True,
+    ) -> None:
+        if protocol not in _VALID_PROTOCOLS:
+            raise ValueError(
+                f"protocol debe ser uno de {_VALID_PROTOCOLS!r}, recibido {protocol!r}"
+            )
+
+        base_url = f"{protocol}://{host}:{port}"
+        logger.debug("Inicializando OSAMClient hacia %s", base_url)
+
+        self._transport = HttpTransport(
+            base_url=base_url,
+            timeout=timeout,
+            verify_ssl=verify_ssl,
+        )
+
+        self.identity = IdentityAPI(self._transport)
+        self.authentication = AuthenticationAPI(self._transport)
+        self.domains = DomainsAPI(self._transport)
+        self.tunnels = TunnelsAPI(self._transport)
+        self.sessions = SessionsAPI(self._transport)
+        self.passports = PassportsAPI(self._transport)
+        self.entities = EntitiesAPI(self._transport)
+
+    async def close(self) -> None:
+        """Cierra las conexiones HTTP subyacentes. Idempotente."""
+        await self._transport.aclose()
+
+    async def __aenter__(self) -> "OSAMClient":
+        return self
+
+    async def __aexit__(self, *exc_info: object) -> None:
+        await self.close()

openshell_shared-0.1.5/openshell_shared/api/manager/v1/domains.py

@@ -0,0 +1,64 @@
+# shared/api/manager/v1/domains.py
+"""
+Dominio: Domains.
+
+Encapsula la consulta de los dominios a los que pertenece la entidad
+autenticada. El servidor solo expone, por ahora, un endpoint de listado
+(``query``); este módulo añade ``get_domain`` como utilidad de "detalle"
+construida en el lado del cliente (filtrando la lista), ya que el servidor
+no expone todavía un endpoint dedicado para un único dominio.
+
+Endpoints cubiertos:
+    POST /api/v/1/domains/query
+"""
+
+from __future__ import annotations
+
+from typing import List, Optional
+
+from .models import Domain
+from .transport import HttpTransport
+
+_PREFIX = "/api/v/1/domains"
+
+
+class DomainsAPI:
+    """API especializada para consultar dominios de OSAM."""
+
+    def __init__(self, transport: HttpTransport) -> None:
+        self._transport = transport
+
+    async def query(self, auth_token: str) -> List[Domain]:
+        """
+        POST /api/v/1/domains/query
+
+        Devuelve la lista de dominios a los que pertenece la entidad
+        identificada por ``auth_token``.
+        """
+        body = await self._transport.post(
+            f"{_PREFIX}/query",
+            json={"auth_token": auth_token},
+        )
+        # El servidor devuelve la lista de dominios como cuerpo JSON raíz;
+        # HttpTransport la normaliza como {"items": [...]} para mantener
+        # una interfaz homogénea (ver HttpTransport._parse_body).
+        items = body.get("items", [])
+        if not isinstance(items, list):
+            items = []
+        
+        return items
+
+    async def get_domain(
+        self, auth_token: str, domain_uid: str
+    ) -> Optional[Domain]:
+        """
+        Utilidad de conveniencia: obtiene un dominio concreto filtrando el
+        resultado de :meth:`query`. No existe (todavía) un endpoint de
+        servidor dedicado a la consulta de un único dominio.
+        """
+        domains = await self.query(auth_token)
+        print(domains)
+        for domain in domains:
+            if domain.uid == domain_uid:
+                return domain
+        return None

openshell_shared-0.1.5/openshell_shared/api/manager/v1/entities.py

@@ -0,0 +1,97 @@
+# shared/api/manager/v1/entities.py
+"""
+Dominio: Entities.
+
+Encapsula la consulta de entidades visibles para el solicitante. La API
+actual del servidor solo expone consulta de entidades de tipo ``AGENT``
+(``/entities/agent/query``); no existe todavía un endpoint genérico por
+tipo arbitrario ni un filtro por dominio. Este módulo expone:
+
+* ``query_agents``: llamada directa al único endpoint real disponible.
+* ``query``: punto de extensión genérico preparado para cuando el servidor
+  exponga más tipos de entidad; hoy delega en ``query_agents`` para
+  ``entity_type in (None, "AGENT")`` y lanza ``NotImplementedError`` para
+  cualquier otro valor, dejando explícito qué falta en el servidor.
+* ``query_by_domain``: punto de extensión, no soportado aún por el servidor.
+* ``get_agent``: utilidad de conveniencia que filtra del lado del cliente.
+
+Endpoints cubiertos:
+    POST /api/v/1/entities/agent/query
+"""
+
+from __future__ import annotations
+
+from typing import List, Optional
+
+from .models import Entity
+from .transport import HttpTransport
+
+_PREFIX = "/api/v/1/entities"
+
+
+class EntitiesAPI:
+    """API especializada para consultar entidades visibles en OSAM."""
+
+    def __init__(self, transport: HttpTransport) -> None:
+        self._transport = transport
+
+    async def query_agents(self, auth_token: str) -> list:
+        """
+        POST /api/v/1/entities/agent/query
+
+        Devuelve las entidades de tipo AGENT visibles para la entidad
+        identificada por ``auth_token``, cada una con su ``status`` de
+        túnel actual.
+        """
+        body = await self._transport.post(
+            f"{_PREFIX}/agent/query",
+            json={"auth_token": auth_token},
+        )
+        entities = body.get("entities", [])
+        if not isinstance(entities, list):
+            entities = []
+        return entities
+
+    async def query(
+        self, auth_token: str, entity_type: Optional[str] = None
+    ) -> list:
+        """
+        Punto de extensión genérico por tipo de entidad.
+
+        Actualmente el servidor solo soporta ``entity_type in (None, "AGENT")``;
+        cualquier otro valor lanza ``NotImplementedError`` de forma explícita
+        en vez de devolver un resultado vacío silencioso.
+        """
+        if entity_type not in (None, "AGENT"):
+            raise NotImplementedError(
+                "El servidor de OSAM solo expone consulta de entidades "
+                "AGENT en esta versión de la API "
+                "(/api/v/1/entities/agent/query). "
+                f"entity_type={entity_type!r} no está soportado todavía."
+            )
+        return await self.query_agents(auth_token)
+
+    async def query_by_domain(self, auth_token: str, domain_uid: str) -> List[Entity]:
+        """
+        Punto de extensión: el servidor no expone (todavía) filtrado de
+        entidades por dominio. Queda declarado aquí para que, cuando se
+        añada el endpoint correspondiente, solo haya que actualizar la
+        implementación de este método sin tocar el resto de la SDK.
+        """
+        raise NotImplementedError(
+            "El servidor de OSAM no expone todavía un endpoint de consulta "
+            "de entidades filtrado por dominio."
+        )
+
+    async def get_agent(
+        self, auth_token: str, entity_uid: str
+    ) -> Optional[Entity]:
+        """
+        Utilidad de conveniencia: obtiene un AGENT concreto filtrando el
+        resultado de :meth:`query_agents` del lado del cliente.
+        """
+        agents = await self.query_agents(auth_token)
+        for agent in agents:
+            if agent.entity_uid == entity_uid:
+                return agent
+        return None