kedgeway

Documentación / Uso / Autenticación

Autenticación

Los datos del ecosistema en vivo provienen del servidor MCP Stellar Raven, que requiere OAuth. kedgeway inicia tu sesión una vez y guarda el token en tu máquina.

Cómo funciona el inicio de sesión

  1. Registro dinámico de cliente. kedgeway se registra en Raven como un cliente llamado kedgeway con el scope mcp. La herramienta no incluye ningún client secret.
  2. PKCE. Se genera un code verifier para el inicio de sesión y se usa para completar el intercambio del código.
  3. Callback local. kedgeway inicia un servidor HTTP de un solo uso en 127.0.0.1 para recibir la redirección. Reutiliza el puerto de tu último inicio de sesión cuando puede; si no, el sistema operativo elige uno. La redirección lleva un valor de state que debe coincidir, así que las solicitudes ajenas se ignoran.
  4. Navegador. La URL de autorización siempre se imprime en stderr. kedgeway también intenta abrirla con open (macOS), xdg-open (Linux) o start (Windows).
  5. Token. El código se intercambia por un token y se guarda.

El callback espera hasta 5 minutos a que autorices.

Cuándo te pide iniciar sesión

kedgeway login inicia una autorización nueva: primero borra el token guardado, el registro del cliente y el verifier. login --export no los borra. Imprime lo que ya está guardado y solo inicia sesión cuando no hay nada guardado. kedgeway diagnose primero prueba tu token guardado en silencio, sin servidor y sin navegador. Solo si Raven responde 401 inicia el flujo interactivo.

Dónde se guarda el token

Terminal
~/.config/kedgeway/auth.json

La carpeta se crea con modo 0700 y el archivo se escribe con modo 0600, mediante un archivo temporal y un cambio de nombre. Contiene los tokens de OAuth, el registro del cliente y el último puerto de callback.

Para borrarlo:

Terminal
kedgeway logout

Qué se envía a Raven

Solo un script fijo, ejecutado con la herramienta execute de Raven. Pide la página Software Versions, el índice de toolchains de Scout y una búsqueda en la documentación. No incluye nada de tu repo. Los nombres de archivo, los manifiestos y las versiones se quedan en tu máquina; la comparación se hace localmente.

Inicio de sesión sin navegador

El servidor OAuth de Raven solo ofrece authorization code con PKCE y refresh tokens, sin device-code grant, así que no hay flujo --device. En una máquina sin navegador, usa:

Terminal
kedgeway login --no-browser

kedgeway imprime la URL de autorización y no intenta abrir un navegador. Ábrela en cualquier navegador e inicia sesión. Después, el navegador se redirige a http://127.0.0.1:<port>/callback, que solo existe en la máquina donde corre kedgeway. Hay dos formas de terminar:

  • Pégala de vuelta. Copia la URL de redirección completa (o solo su code) en la terminal y presiona Enter. Una entrada incorrecta muestra un error de una línea y la solicitud se repite.
  • Reenvía el puerto. Desde tu propia máquina, antes de iniciar sesión, reenvía el puerto del callback para que la redirección llegue directamente a kedgeway. El puerto está en el redirect_uri de la URL impresa.
Terminal
ssh -L <port>:127.0.0.1:<port> user@remote-host

Una URL pegada se compara con el state de OAuth del intento de inicio de sesión, y la verificación falla de forma segura: si no hay state para comparar, la URL pegada se rechaza. Un código suelto no lleva state, así que no se puede verificar. Cuando stdin no es una terminal, pegar está deshabilitado y solo el callback puede terminar el inicio de sesión.

Para CI, haz esto una vez en una máquina de confianza y agrega --export para imprimir el secreto después:

Terminal
kedgeway login --no-browser --export

En CI

Ejecuta kedgeway login --export para imprimir tus credenciales guardadas como un secreto en base64 y guárdalo en un secreto KEDGEWAY_AUTH. Durante la ejecución, la variable reemplaza a auth.json: nunca se escribe en disco y se renueva solo en memoria, así que un refresh token rotado puede dejarla vencida. Consulta CI.

Solución de problemas

El puerto está ocupado
kedgeway usa otro puerto libre en 127.0.0.1. No tienes que hacer nada.
El navegador no se abrió
Copia la URL impresa en la terminal (stderr) en un navegador de la misma máquina. En un servidor sin navegador, consulta Inicio de sesión sin navegador.
Se agotó el tiempo de inicio de sesión
El callback se rinde después de 5 minutos. Vuelve a ejecutar kedgeway login.
El token fue rechazado
kedgeway reporta que la autenticación funcionó, pero Raven rechazó el token. Ejecuta kedgeway logout y luego kedgeway login.