Configuración remota (WSS)

Conecta zerocode en tu estación de trabajo a un daemon que se ejecuta en otra máquina (Raspberry Pi, servidor doméstico, VPS, etc.).

Para consultar la guía completa, opción por opción, que cubre las tres topologías (directa, demonio a retransmisor y cliente a través de retransmisor), consulta Transporte seguro (configuración de extremo a extremo).

El plano WSS está autenticado mutuamente (mTLS). Cada cliente presenta un certificado; no existe una ruta solo de servidor/sin autenticación. La forma sencilla de obtener un certificado de cliente es el registro (a continuación): no tienes que gestionar certificados manualmente. Si prefieres generar uno tú mismo, consulta más abajo los pasos para usar tu propio certificado en “En tu estación de trabajo”. --tls-skip-verify solo relaja la verificación del certificado del servidor para un certificado autofirmado del demonio; el certificado de cliente sigue siendo obligatorio en cualquier caso.

Necesitas dos cosas: un certificado y un token de portador. El certificado de cliente protege el transporte: demuestra qué dispositivo está al otro lado de la conexión TLS. No indica quién eres. Toda conexión remota también debe presentar un token de portador en el handshake initialize, y ese token es el que te identifica (consulta Bearer token más abajo). La inscripción solo te proporciona el certificado. Un cliente con certificado pero sin token completa el handshake TLS y después es rechazado con AUTH_REQUIRED (-32010).

Inscripción (recomendada)

La primera vez que conectes un cliente sin certificado de forma interactiva, zerocode se registra automáticamente:

zerocode --connect wss://<remote-host>:9781

Solicita el código de emparejamiento de un solo uso del daemon (impreso en el registro del daemon al iniciarse) y muestra una cadena corta de autenticación (SAS) para confirmarla en la consola del daemon, de modo que se detecte una CA de tipo man-in-the-middle. Después obtiene y almacena en caché un certificado de cliente en <config-dir>/tls. Las ejecuciones posteriores reutilizan ese certificado sin volver a solicitar nada, y se renueva automáticamente al ~50% de su vida útil. Para registrarse de forma no interactiva, usa zerocode --enroll --connect wss://<remote-host>:9781.

La inscripción no te proporciona un token Bearer. El código de emparejamiento de inscripción es independiente del código de emparejamiento del gateway, y se consume durante la inscripción. Aun así, necesitas un token antes de que el daemon acepte una sesión; consulta token Bearer.

Un cliente sin certificado que accede al plano WSS sin inscribirse recibe un mensaje accionable («inscríbase primero») y el demonio registra el cliente rechazado que no se ha migrado; nunca se queda bloqueado silenciosamente. Un certificado revocado se rechaza durante el protocolo de enlace (según el registro de certificados emitidos), por lo que revocar un dispositivo perdido surte efecto en su próxima conexión.

allow_unpaired_enrollment en la sección [enroll] está reservado para un flujo futuro de migración sin código. Esta versión rechaza cualquier valor no vacío al iniciar el daemon; déjelo vacío y use el código de emparejamiento mostrado.

En el host remoto (lado del daemon)

1. Habilita WSS. Establece la configuración de wss mediante el panel de configuración (o la puerta de enlace / zeroclaw config set):

   [wss]
   enabled = true
   

   Deja cert_path / key_path vacíos (el valor predeterminado): el demonio genera automáticamente su propia CA y el certificado del servidor en <data_dir>/tls/ durante el primer arranque, por lo que no necesitas ejecutar openssl por tu cuenta. Establécelos solo para usar tu propio certificado de servidor y, en cualquier caso, utiliza rutas absolutas; la configuración no expande ~.

2. Abrir el puerto del firewall:

   sh

   sudo ufw allow 9781/tcp
   

   El puerto WSS predeterminado es 9781. Cámbialo con port = <number> en la sección [wss].

3. Inicia (o reinicia) el daemon:

   sh

   zeroclaw daemon
   

   Deberías ver una línea de registro confirmando que el receptor WSS se inició en 0.0.0.0:9781.

En tu estación de trabajo (lado zerocode)

El registro (más arriba) es la forma más rápida de obtener un certificado de cliente. Si prefiere usar su propio certificado de cliente en lugar de registrarse de forma interactiva:

1. Emite un certificado de cliente en el host del daemon, desde la CA de mTLS del daemon:

   zeroclaw security issue-client-cert --name my-laptop --out-dir /tmp/my-laptop-tls
   

   Esto escribe ca.crt, client.crt y client.key en --out-dir. Añade --force para sobrescribir un certificado existente con ese nombre.

2. Copie los tres archivos en <config-dir>/tls/ de la estación de trabajo (después, zerocode --connect wss://<remote-ip>:9781 los encuentra automáticamente), o indique sus rutas explícitamente:

   sh

   zerocode --connect wss://<remote-ip>:9781 \
     --tls-ca-cert     /path/ca.crt \
     --tls-client-cert /path/client.crt \
     --tls-client-key  /path/client.key
   

   Como ca.crt es la misma CA que firmó el certificado del servidor del demonio, esto también verifica el servidor; --tls-skip-verify solo es necesario si omites --tls-ca-cert al usar un certificado autofirmado del demonio que no hayas fijado.

En cualquier caso, el certificado solo te permite superar la capa TLS. A continuación, añade un token de portador.

Token de portador (obligatorio para cada conexión)

El daemon rechaza cualquier initialize remoto que no tenga auth_token, incluso cuando el certificado de cliente es válido. Proporciona un token a zerocode una sola vez, y lo presentará en cada conexión y reconexión.

1. Vincula con la puerta de enlace para obtener un token. Usa la página de Emparejamiento del panel o, en el host del daemon (la puerta de enlace escucha en 127.0.0.1:42617 por defecto), envía con POST el código de emparejamiento de la puerta de enlace que aparece en el registro del daemon a /pair:

   curl -X POST http://127.0.0.1:42617/pair -H 'X-Pairing-Code: <code>'
   

   No tengo ningún código de emparejamiento de la puerta de enlace ni un código de inscripción de zerocode en esta conversación, así que no puedo sustituir ningún token.

   Soy un traductor de cadenas de documentación técnica del inglés al español. Si me pasas la cadena, la devuelvo traducida y conservo zc_... y zerocode exactamente como aparecen.

2. Dale el token a zerocode. La variable de entorno es la forma recomendada, porque mantiene el secreto fuera del archivo de configuración:

   export ZEROCLAW_AUTH_TOKEN=zc_...
   zerocode --connect wss://<remote-host>:9781
   

   O configúralo en la configuración de zerocode, ya sea como una ruta a un archivo que solo tú puedes leer o en línea:

   [connection.wss]
   uri = "wss://<remote-host>:9781"
   auth_token_file = "/abs/path/zerocode-bearer"   # o: auth_token = "zc_..."
   

   Orden de precedencia: ZEROCLAW_AUTH_TOKEN, luego auth_token_file y, por último, auth_token. Un archivo de token que otras cuentas pueden leer se omite con una advertencia.

Para usar un token de acceso OIDC en lugar de un token de emparejamiento, también establece auth_provider = "oidc.<alias>" bajo [connection.wss]. Para las reglas de permisos de archivos, OIDC y lo que hace el demonio con el token, consulta Autenticación y principales.

Después de eso, zerocode --connect wss://<remote-host>:9781 (o simplemente zerocode con uri en la configuración) no necesita más flags, y zerocode se reconecta automáticamente si la conexión se interrumpe.

Referencia de configuración

La sección wss: