El token de acceso y quién llega al relay

Un relay tiene un propietario y un token de acceso. Quien tenga el token tiene el control total del relay y, a través de sus agentes, de la cuenta de usuario con la que se ejecuta el relay. No hay cuentas de usuario, roles ni claves por dispositivo. Esta página explica de dónde sale el token, cómo lo presenta un navegador o un script, quién puede conectarse, qué es accesible sin él y qué hacer si se filtra.

El token #

oar setup crea el token (uno aleatorio en una configuración nueva, 43 caracteres aleatorios entre letras, dígitos, - y _) y lo escribe en authToken en el archivo de configuración, config.json, en la carpeta de estado de OAR. Fuera de Windows, el relay mantiene ese archivo legible solo para ti. Consulta config.json y Dónde se guardan los secretos.

Sin un authToken en la configuración, el relay crea un token aleatorio en cada arranque, lo imprime en su registro y no lo guarda. Si arrancas el relay con --token <value>, ese token se usa solo durante esa ejecución; nunca se guarda y forma parte de la línea de comandos. Tus agentes leen el token de config.json (consulta Los agentes y el token), así que usa un token guardado allí si quieres que los agentes funcionen.

oar url imprime la dirección con el token actual, por ejemplo http://localhost:3333/?token=<your token>. Trata esa dirección como una contraseña.

Formas de presentarlo #

El token nunca se lee del cuerpo de una solicitud ni, desde 0.9.11, de la query de una solicitud. Si una solicitud lleva a la vez una cabecera y la cookie, el relay usa la cabecera. Un valor incorrecto no se pasa por alto: una cabecera incorrecta se rechaza aunque la cookie sea correcta. La conexión en vivo (Socket.IO) lee el token del campo auth.token de la conexión o de la cookie, no de una cabecera ni de su query.

La cookie de inicio de sesión #

Tras un token válido, el relay fija una cookie llamada copilot_auth que dura 30 días. Esto también ocurre con un script que envía el token en una cabecera. Es HttpOnly, así que los scripts de la página no pueden leerla, y SameSite=Lax. Se marca como Secure cuando se llega al relay por HTTPS. Si llega una solicitud con una cookie que ya no coincide con el token, el relay responde 401 y borra la cookie, y el navegador muestra el cuadro de inicio de sesión. La cookie contiene el propio token.

Cerrar sesión y revocar un dispositivo #

La app no tiene un botón para cerrar sesión en el relay, y el relay no guarda una lista de dispositivos con sesión iniciada. Como la cookie contiene el propio token, no se puede revocar un solo dispositivo. En tu propio navegador, borra la cookie en los ajustes del sitio del navegador. Para dejar fuera a todos los dispositivos, incluido uno que hayas perdido, cambia el token (siguiente sección).

Rotar el token #

oar setup --new-token

Esto escribe un token nuevo y reinicia el relay (en una terminal pregunta antes; consulta oar setup). Qué ocurre:

• Navegadores con sesión iniciada. El token antiguo deja de funcionar cuando el relay se ha reiniciado. El reinicio corta la conexión en vivo, y la siguiente solicitud de cada navegador falla: el relay borra su cookie y el navegador muestra el cuadro de inicio de sesión. Vuelve a iniciar sesión con la dirección de oar url o con el token nuevo.
• Hasta el reinicio. Si rechazas el reinicio, el relay en ejecución sigue aceptando el token antiguo hasta oar restart.
• Relays emparejados. Un relay que tiene guardado tu token, porque emparejaste los dos, recibe Token not accepted (Token no aceptado). Vuelve a añadir el relay allí con el token nuevo; consulta Relays remotos. Quitar un emparejamiento en este relay no revoca un token que el otro lado ya tiene, así que rotar el token es la forma de dejar fuera a ese relay.
• relay-previous.json. Mientras un puerto o token cambiado espera al reinicio, oar setup guarda el puerto y el token antiguos en este archivo de la carpeta de datos (texto plano, legible solo para ti), para que oar status, oar stop y oar restart sigan encontrando el relay en ejecución. No es un periodo de gracia: el archivo no cambia nada de lo que acepta el relay, y los comandos oar lo borran en cuanto el relay responde con los ajustes nuevos. El token antiguo deja de funcionar solo cuando el relay se reinicia.
• Los enlaces compartidos y los enlaces de vista previa tienen sus propios tokens y no se ven afectados.

Editar authToken a mano en el archivo funciona igual; oar restart lo aplica.

Quién puede conectarse #

localhostOnly en la configuración decide dónde escucha el relay:

Solo el booleano true y el texto "true" (en mayúsculas o minúsculas) cuentan como local. false, null, 1, "yes" y cualquier otro valor abren el relay a la red; el valor predeterminado solo se aplica cuando falta la clave. oar setup escribe la clave como true o false. Un cambio necesita oar restart.

oar setup, oar url y oar status leen la clave de otra forma: para ellos solo el booleano false cuenta como acceso LAN, y oar doctor muestra localhostOnly: no solo con false. Con un valor como null o "no" el relay escucha en todas las interfaces mientras esos comandos informan this machine only (solo esta máquina). Limita la clave a true o false. Consulta config.json.

En una LAN, el token es la única barrera: el relay no comprueba de dónde viene una solicitud. Con el acceso this machine only, un teléfono no puede conectarse hasta que actives el acceso LAN o uses un túnel. localhostOnly no afecta a los túneles gestionados, que se conectan hacia fuera desde la máquina.

Un relay que está detrás de un proxy o un túnel en la misma máquina puede quedarse en this machine only. Qué proxies le merecen confianza al relay para sus cabeceras X-Forwarded-* lo fija trustProxy (predeterminado loopback); eso decide si trata una conexión como HTTPS y marca la cookie como Secure.

Qué necesita el token #

Todo lo que lee o cambia tus conversaciones, archivos, ajustes o agentes necesita el token. Estas son las excepciones, y la lista completa.

No hay ningún endpoint de salud o de versión sin autenticación: /api/status, al que llama oar status, necesita el token.

Los enlaces compartidos y los enlaces de vista previa son públicos por diseño. El token aleatorio del enlace es su única protección, así que ciérralos o revócalos cuando termines. Los archivos que sirve el relay se envían con una política de sandbox, así que un archivo HTML o SVG servido no puede ejecutar scripts en el origen del relay.

La conexión de los workers solo responde a solicitudes de la propia máquina del relay que no haya reenviado ningún proxy ni túnel; todo lo demás se rechaza con 403 antes de comprobar el token. Los enlaces compartidos a través de un túnel no se ven afectados. Consulta La protección de rutas del worker de sesión.

Protecciones en el inicio de sesión #

• Para el inicio de sesión y la conexión en vivo, el relay compara los tokens en tiempo constante.
• Nuevo en 0.9.11 Diez tokens incorrectos bloquean una dirección durante un minuto. Diez tokens incorrectos desde una misma dirección de cliente en un minuto, en una cabecera, la cookie, el cuadro de inicio de sesión o el handshake de una conexión en vivo, hacen que el relay responda a esa dirección 429 con Retry-After hasta que pase el minuto, incluido el token correcto. El cuadro de inicio de sesión dice Too many failed sign-in attempts. Try again in 42 seconds. (Demasiados intentos de inicio de sesión fallidos. Vuelve a intentarlo en 42 segundos.). El mismo valor incorrecto repetido cuenta una vez, así que una pestaña con una cookie antigua no te bloquea. El relay registra una línea que empieza por [auth] cuando rechaza una dirección.
• Las solicitudes de la propia máquina del relay que no haya reenviado ningún proxy ni túnel nunca se cuentan ni se bloquean, así que los workers del relay y las herramientas de los agentes siguen funcionando.
• La dirección del cliente es aquella en la que el relay confía. Detrás de un proxy en otra máquina en el que el relay no confía, todos los clientes tienen la dirección del proxy, y los tokens incorrectos de un cliente los bloquean a todos.
• El bloqueo frena los intentos de adivinar; no sustituye a un buen token. Mantén el token largo y aleatorio: oar setup genera uno; no lo cambies por una palabra corta.
• El único límite de frecuencia en rutas que no necesitan token es el de los pings de presencia de las conversaciones compartidas: 24 cada 10 segundos por enlace compartido y dirección de cliente. Nuevo en 0.9.11 La dirección del cliente sigue a trustProxy, como el bloqueo, así que un cliente no puede elegir la suya enviando X-Forwarded-For.
• El token no se escribe en el registro, salvo cuando la configuración no tiene ninguno y el relay crea uno temporal al arrancar. oar start y oar url lo imprimen en tu terminal.

Los agentes y el token #

Tus agentes se ejecutan como procesos del usuario con el que se ejecuta el relay, en la máquina del relay. No reciben credenciales propias: para hablar con el relay leen el propio token del relay de config.json y lo envían como lo haría el propietario. El relay no pone el token en el entorno ni en el prompt de un agente, pero un agente se ejecuta con el mismo usuario del sistema operativo, así que puede leer el archivo y, con él, el token. Lo mismo vale para todo lo que ejecute un agente. Da por hecho que todos los agentes que ejecutas conocen el token, y ejecuta agentes solo con un usuario al que confiarías el relay.

El relay no comunica a los agentes el token de un relay emparejado: los agentes llegan a un relay emparejado a través de este relay, que añade el token guardado (Relays remotos). Un agente también actúa con los permisos del usuario con el que se ejecuta el relay, así que cualquier cosa que el propietario del relay pueda hacer en la máquina se le puede pedir a un agente.

HTTP sin cifrar en una LAN #

Con acceso LAN y una dirección http://, el token y la cookie cruzan la red sin cifrar. Cualquiera que pueda observar ese tráfico puede leer el token. Úsalo en una red de confianza o pon HTTPS delante. Con HTTP sin cifrar, la cookie no se marca como Secure.

Instalar OAR como app y las notificaciones push necesitan HTTPS o localhost, así que ninguna de las dos funciona con una dirección LAN sin cifrar: consulta Instalar como app y Notificaciones.

Si crees que el token se filtró #

1. Ejecuta oar setup --new-token y deja que reinicie el relay. Todos los navegadores pierden la sesión. Si rechazas el reinicio, ejecuta oar restart: hasta entonces el token antiguo sigue funcionando.
2. Vuelve a iniciar sesión con la dirección de oar url.
3. En cada relay que emparejaste con este, vuelve a añadir este relay con el token nuevo (Relays remotos).
4. Comprueba dónde se guardó el token: scripts, historial de la shell, la dirección que pegaste en un chat y copias o copias de seguridad de config.json.
5. Detén o renueva los enlaces compartidos en Settings → Sharing (Ajustes → Compartir) (Tus enlaces compartidos) y cierra las vistas previas que no reconozcas. Esos tienen sus propios tokens.
6. Si alguien pudo usar el relay mientras estaba expuesto, revisa lo que hicieron sus agentes. Quien tiene el token puede iniciar agentes que ejecutan comandos como el usuario del relay.