Refactor de Clawnet: Unificando protocolos y autenticación

¿Alguna vez has sentido que mantener dos protocolos diferentes para lo mismo es una pesadilla? Tener el control plane en un lado y el transporte de datos en otro solo genera duplicación de código y problemas de identidad. Es frustrante cuando una aprobación de seguridad aparece en una máquina remota en lugar de aparecer frente a ti, donde realmente estás trabajando.

Estamos moviendo todo hacia Clawnet, unificando el protocolo y la autenticación para que el desarrollo sea más limpio y la seguridad sea real.

Requisitos previos

• Acceso al Gateway (control plane).
• Cliente compatible con WebSocket (WS).
• Soporte para TLS y fingerprint pinning.
• Un deviceId estable (generado a partir de una llave pública).

Inicio rápido

Configura tu conexión en 5 minutos siguiendo estos pasos:

1. Define tu rol y scope: Decide si tu cliente se conectará como node (para ejecutar acciones) o como operator (para administrar). Si eres operador, define si necesitas operator.read, operator.write, operator.admin u operator.approvals.
2. Genera tu identidad: Crea un par de llaves criptográficas en tu dispositivo. Tu deviceId será el fingerprint de tu llave pública.
3. Inicia el pairing: Conéctate al Gateway sin autenticación. Esto generará una pairing request. Un operador activo deberá aprobar tu dispositivo desde su UI.
4. Conexión segura: Tras la aprobación, el Gateway te entregará credenciales vinculadas a tu llave pública. Reconéctate usando TLS con pinning para empezar a trabajar.

El nuevo modelo de Clawnet

Hemos pasado de tener una estructura fragmentada a un sistema de un solo protocolo con dos roles definidos.

Un protocolo, dos roles

En lugar de separar el tráfico, usamos WebSocket para todo, diferenciando el comportamiento según el rol:

• Node: Es el host de capacidades. Registra comandos (como system.run o camera.*) y recibe instrucciones de ejecución. No puede acceder a las API de configuración o modelos.
• Operator: Es el centro de control. Tiene acceso a las API del Gateway según su scope y es quien recibe las solicitudes de aprobación.

Aprobaciones centralizadas

Antes, las aprobaciones ocurrían en el host del nodo, lo que no tenía sentido si estabas controlando todo desde tu teléfono. Ahora, el flujo es directo:

1. El Gateway recibe una intención (ej. un agente quiere ejecutar algo).
2. Se crea un registro de approval.requested.
3. La UI del Operator muestra el prompt, sin importar dónde esté el nodo físicamente.
4. Si el operador aprueba, el Gateway invoca el comando en el nodo.

Seguridad y TLS

Hemos eliminado la dependencia de SSH o Tailscale para la seguridad en remoto. Aplicamos TLS con pinning de certificados en todas las conexiones WebSocket. El deviceId ya no es un simple string, sino que está vinculado a una prueba de posesión de llave privada, evitando que los tokens robados puedan ser reutilizados en otros dispositivos.

Solución de problemas

• El prompt de aprobación no aparece: Asegúrate de que tu cliente tenga el scope operator.approvals. Solo los clientes con este permiso reciben las solicitudes de resolución.
• Error de identidad duplicada: Si una misma máquina aparece dos veces en la UI, verifica que ambos roles (node y operator) estén usando el mismo deviceId.
• Conexión rechazada por TLS: Revisa el fingerprint anunciado en el discovery TXT. Si el certificado del Gateway cambió, deberás actualizar el pinning en el cliente.
• Timeout en aprobaciones: Por seguridad, las solicitudes expiran tras 60 segundos. Si no respondes a tiempo, el Gateway denegará la acción automáticamente.

Si necesitas ayuda para configurar tu entorno específico, consulta al AI Setup Assistant.

Próximos pasos

• Gateway Protocol Documentation
• Bridge Protocol Legacy Reference
• Identity and Pairing Specs
• TLS Implementation Details