Refactorización de Clawnet (unificación de protocolo + autenticación)

Propósito

Documento único y riguroso para:

  • Estado actual: protocolos, flujos, límites de confianza.
  • Puntos de dolor: aprobaciones, enrutamiento multi-hop, duplicación de UI.
  • Nuevo estado propuesto: un protocolo, roles con alcance, autenticación/emparejamiento unificados, pinning TLS.
  • Modelo de identidad: IDs estables + slugs simpáticos.
  • Plan de migración, riesgos, preguntas abiertas.

Objetivos

  • Un protocolo para todos los clientes (app mac, CLI, iOS, Android, nodo headless).
  • Cada participante de red autenticado + emparejado.
  • Claridad de roles: nodos vs operadores.
  • Aprobaciones centrales enrutadas a donde está el usuario.
  • Encriptación TLS + pinning opcional para todo el tráfico remoto.
  • Duplicación mínima de código.
  • Una máquina debería aparecer una sola vez (sin entrada duplicada UI/nodo).

No objetivos

  • Eliminar la separación de capacidades (sigue necesitándose privilegio mínimo).
  • Exponer el plano de control completo del gateway sin verificaciones de alcance.
  • Hacer que la autenticación dependa de etiquetas humanas (los slugs siguen sin ser de seguridad).

Estado actual

Dos protocolos

  1. WebSocket del Gateway (plano de control): superficie API completa, bind loopback por defecto, autenticación por token/password.
  2. Bridge (transporte de nodos): superficie con lista de permitidos estrecha, identidad de nodo + emparejamiento, JSONL sobre TCP con TLS opcional + pinning de fingerprint.

Problemas / puntos de dolor

  • Dos pilas de protocolo a mantener (WS + Bridge).
  • Aprobaciones en nodos remotos: el prompt aparece en el host del nodo, no donde está el usuario.
  • El pinning TLS solo existe para bridge; WS depende de SSH/Tailscale.
  • Duplicación de identidad: la misma máquina aparece como múltiples instancias.
  • Roles ambiguos: las capacidades de UI + nodo + CLI no están claramente separadas.

Nuevo estado propuesto (Clawnet)

Un protocolo, dos roles

Protocolo WS único con rol + alcance.

  • Rol: nodo (host de capacidades)
  • Rol: operador (plano de control)
  • Alcance opcional para operador: operator.read, operator.write, operator.admin

Autenticación + emparejamiento unificados

  • Autenticación basada en pares de claves del dispositivo
  • deviceId = fingerprint(publicKey)
  • El gateway envía un nonce; el dispositivo firma; el gateway verifica

TLS en todas partes

  • Reutilizar el runtime TLS existente del bridge
  • Aplicar a WS con el mismo cert/key + fingerprint

Rediseño de aprobaciones (centralizado)

  • Las aprobaciones son alojadas en el gateway, la UI se entrega a los clientes operadores
  • Broadcast a todos los operadores; la primera resolución gana

Identidad + slugs

  • ID estable: Fingerprint del par de claves (hash de clave pública)
  • Slug simpático (temática de langosta): Etiqueta humana, ej. scarlet-claw, saltwave, mantis-pinch

Estrategia de migración

  • Fase 0: Documentar + alinear
  • Fase 1: Agregar roles/alcances a WS
  • Fase 2: Compatibilidad con bridge
  • Fase 3: Aprobaciones centrales
  • Fase 4: Unificación TLS
  • Fase 5: Deprecar bridge
  • Fase 6: Autenticación vinculada al dispositivo

Resumen

  • Hoy: plano de control WS + transporte de nodo Bridge.
  • Dolor: aprobaciones + duplicación + dos pilas.
  • Propuesta: un protocolo WS con roles explícitos + alcances, emparejamiento unificado + pinning TLS, aprobaciones alojadas en el gateway, IDs de dispositivo estables + slugs simpáticos.
  • Resultado: UX más simple, seguridad más fuerte, menos duplicación, mejor enrutamiento móvil.
Siguiente
Overview
arrow_forward