openshell-shared 0.1.2__tar.gz

openshell_shared-0.1.2/PKG-INFO

@@ -0,0 +1,59 @@
+Metadata-Version: 2.4
+Name: openshell-shared
+Version: 0.1.2
+Summary: Shared library for OpenShell (OSAM/OSA/OSAC)
+Author: Daniel Pérez
+License: Proprietary
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+Requires-Dist: httpx
+Requires-Dist: cryptography
+Requires-Dist: websockets
+Requires-Dist: uuid6
+
+# OpenShell Shared
+
+Librería compartida usada por los componentes de OpenShell (OSAM, OSA, OSAC).
+
+Contiene:
+
+- **identity/** — Identidad lógica de las entidades (`EntityIdentity`, `Identification`) y su
+  persistencia (`store.py`).
+- **cryptography/** — Primitivas Ed25519 (`keys.py`, `signatures.py`), identidad criptográfica
+  (`identity.py`) y certificados (`certificate.py`). `encoding.py` y `utils.py` son módulos
+  reservados para trabajo futuro (actualmente sin implementación).
+- **protocols/negotiation/** — Protocolo de challenge-response (`challenge.py`) y sus modelos.
+- **domain/** — Modelo de dominio (`Domain`, `Membership`, `Permission`) y políticas de
+  autorización. `policies.py` es un stub pendiente de implementación real.
+- **standards/** — Enumeraciones y contratos compartidos entre componentes: tipos de entidad,
+  certificados, eventos, roles, permisos, passports y transportes.
+- **modules/shell/** — Implementación del subsistema de shell remoto (cliente, servidor, sesión
+  y protocolo de framing) usado por OSA y OSAC.
+- **api/manager/v1/** — SDK oficial async para consumir la API HTTP de OSAM (`OSAMClient`).
+  Todo el sistema (OSAC, OSA, herramientas internas) debe consumir OSAM exclusivamente a través
+  de este paquete; ningún otro componente debe importar `httpx`/`requests` directamente para
+  hablar con OSAM.
+
+## Notas de la fusión (v2.1.0)
+
+Esta versión unifica dos ramas que habían divergido:
+
+- Se conserva la estructura de empaquetado (`pyproject.toml`, layout `src`) y los módulos
+  `domain/` y `standards/`, introducidos en la rama de refactor v2.
+- Se restaura `modules/shell/` y se sustituye el cliente HTTP monolítico
+  (`api/manager/1/osam_client.py`) por el SDK modular (`api/manager/v1/`), que es la versión
+  vigente y más completa (excepciones tipadas, dataclasses, suite de tests con mock transport).
+
+### Deuda técnica pendiente identificada durante la fusión
+
+1. `domain/permissions.py` y `standards/permissions/types.py` definen dos enums `Permission`
+   distintos y no compatibles entre sí (`AGENT_READ/AGENT_EXECUTE/DOMAIN_ADMIN/PROXY_USE` vs.
+   `DOMAIN_READ/DOMAIN_WRITE/ENTITY_REGISTER/ENTITY_REVOKE/PROXY_USE`). No se han unificado
+   automáticamente porque implica una decisión de diseño (cuál es la fuente de verdad de
+   permisos). Requiere consolidación manual.
+2. `cryptography/encoding.py`, `cryptography/utils.py` y `domain/policies.py` son placeholders
+   vacíos o triviales (`Policy.evaluate` siempre retorna `True`). No implementan lógica real.
+3. El SDK (`api/manager/v1/`) no reexpone los helpers de alto nivel `full_connect` /
+   `open_and_link` que existían en el cliente monolítico anterior (composición de
+   autenticación + túnel + sesión en una sola llamada). Si se siguen usando, conviene
+   reimplementarlos como métodos de conveniencia sobre `OSAMClient`.

openshell_shared-0.1.2/README.md

@@ -0,0 +1,46 @@
+# OpenShell Shared
+
+Librería compartida usada por los componentes de OpenShell (OSAM, OSA, OSAC).
+
+Contiene:
+
+- **identity/** — Identidad lógica de las entidades (`EntityIdentity`, `Identification`) y su
+  persistencia (`store.py`).
+- **cryptography/** — Primitivas Ed25519 (`keys.py`, `signatures.py`), identidad criptográfica
+  (`identity.py`) y certificados (`certificate.py`). `encoding.py` y `utils.py` son módulos
+  reservados para trabajo futuro (actualmente sin implementación).
+- **protocols/negotiation/** — Protocolo de challenge-response (`challenge.py`) y sus modelos.
+- **domain/** — Modelo de dominio (`Domain`, `Membership`, `Permission`) y políticas de
+  autorización. `policies.py` es un stub pendiente de implementación real.
+- **standards/** — Enumeraciones y contratos compartidos entre componentes: tipos de entidad,
+  certificados, eventos, roles, permisos, passports y transportes.
+- **modules/shell/** — Implementación del subsistema de shell remoto (cliente, servidor, sesión
+  y protocolo de framing) usado por OSA y OSAC.
+- **api/manager/v1/** — SDK oficial async para consumir la API HTTP de OSAM (`OSAMClient`).
+  Todo el sistema (OSAC, OSA, herramientas internas) debe consumir OSAM exclusivamente a través
+  de este paquete; ningún otro componente debe importar `httpx`/`requests` directamente para
+  hablar con OSAM.
+
+## Notas de la fusión (v2.1.0)
+
+Esta versión unifica dos ramas que habían divergido:
+
+- Se conserva la estructura de empaquetado (`pyproject.toml`, layout `src`) y los módulos
+  `domain/` y `standards/`, introducidos en la rama de refactor v2.
+- Se restaura `modules/shell/` y se sustituye el cliente HTTP monolítico
+  (`api/manager/1/osam_client.py`) por el SDK modular (`api/manager/v1/`), que es la versión
+  vigente y más completa (excepciones tipadas, dataclasses, suite de tests con mock transport).
+
+### Deuda técnica pendiente identificada durante la fusión
+
+1. `domain/permissions.py` y `standards/permissions/types.py` definen dos enums `Permission`
+   distintos y no compatibles entre sí (`AGENT_READ/AGENT_EXECUTE/DOMAIN_ADMIN/PROXY_USE` vs.
+   `DOMAIN_READ/DOMAIN_WRITE/ENTITY_REGISTER/ENTITY_REVOKE/PROXY_USE`). No se han unificado
+   automáticamente porque implica una decisión de diseño (cuál es la fuente de verdad de
+   permisos). Requiere consolidación manual.
+2. `cryptography/encoding.py`, `cryptography/utils.py` y `domain/policies.py` son placeholders
+   vacíos o triviales (`Policy.evaluate` siempre retorna `True`). No implementan lógica real.
+3. El SDK (`api/manager/v1/`) no reexpone los helpers de alto nivel `full_connect` /
+   `open_and_link` que existían en el cliente monolítico anterior (composición de
+   autenticación + túnel + sesión en una sola llamada). Si se siguen usando, conviene
+   reimplementarlos como métodos de conveniencia sobre `OSAMClient`.

openshell_shared-0.1.2/api/__init__.py

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

openshell_shared-0.1.2/api/manager/__init__.py

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

openshell_shared-0.1.2/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.2/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.2/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.2/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