Arquitectura y diseno

Por que Rust

SSH-Frontière esta escrito en Rust por tres razones:

1. Seguridad de memoria: sin buffer overflow, sin use-after-free, sin null pointer. Para un componente de seguridad que funciona como shell de inicio, esto es critico.

2. Binario estatico: se compila con el target x86_64-unknown-linux-musl (otros targets posibles sin garantia de funcionamiento), el binario ocupa ~1 Mo y no tiene ninguna dependencia del sistema. Se copia en el servidor y listo.

3. Rendimiento: el programa arranca, valida, ejecuta y termina en milisegundos. Sin runtime, sin garbage collector, sin JIT.

Sincrono y efimero

SSH-Frontière es un programa sincrono y one-shot. Sin daemon, sin async, sin Tokio.

El ciclo de vida es simple:

1. sshd autentica la conexion SSH por clave
2. sshd hace fork y ejecuta ssh-frontiere como shell de inicio
3. ssh-frontiere valida y ejecuta el comando
4. El proceso termina

Cada conexion SSH crea un nuevo proceso. Sin estado compartido entre conexiones, sin problemas de concurrencia.

Estructura del codigo

El codigo esta organizado en modulos con responsabilidades claras:

Cada modulo tiene su archivo de tests (*_tests.rs) en el mismo directorio.

Un binario auxiliar proof (src/bin/proof.rs) permite calcular los proofs de autenticacion para los tests E2E y la integracion con clientes.

Protocolo de cabeceras

SSH-Frontière utiliza un protocolo de texto sobre stdin/stdout. Los prefijos difieren segun la direccion:

Cliente hacia servidor (stdin):

Servidor hacia cliente (stdout):

Flujo de conexion

CLIENTE                                 SERVIDOR
  |                                        |
  |  <-- banner + capabilities ----------  |   #> ssh-frontiere 0.1.0
  |                                        |   +> capabilities rbac, session, help, body
  |                                        |   +> challenge nonce=a1b2c3...
  |                                        |   #> type "help" for available commands
  |                                        |
  |  --- +auth (opcional) -------------->  |   + auth token=runner-ci proof=deadbeef...
  |  --- +session (opcional) ----------->  |   + session keepalive
  |                                        |
  |  --- comando (texto plano) --------->  |   forgejo backup-config
  |  --- fin de bloque ----------------->  |   .
  |  <-- streaming stdout ---------------  |   >> Backup completed
  |  <-- respuesta JSON final -----------  |   >>> {"status_code":0,"status_message":"executed",...}
  |                                        |
  |  (si session keepalive)                |
  |  --- comando 2 --------------------->  |   infra healthcheck
  |  --- fin de bloque ----------------->  |   .
  |  <-- respuesta JSON 2 ---------------  |   >>> {"status_code":0,...}
  |  --- fin de sesion (bloque vacio) -->  |   .
  |  <-- session closed ------------------  |   #> session closed

Respuesta JSON

Cada comando produce una respuesta JSON final en una sola linea, prefijada por >>>. La salida estandar y de error se envian en streaming mediante >> y >>!:

>> Backup completed
>>> {"command":"forgejo backup-config","status_code":0,"status_message":"executed","stdout":null,"stderr":null}

• stdout/stderr = null en la respuesta JSON final: la salida fue enviada en streaming via >> y >>!
• Para los comandos no ejecutados (rechazo, error de config), stdout y stderr tambien son null

Protocolo body

La cabecera +body permite transmitir contenido multilínea al proceso hijo via stdin. Cuatro modos de delimitacion:

• +body: lee hasta una linea que contenga unicamente . (punto)
• +body size=N: lee exactamente N bytes
• +body stop="DELIMITADOR": lee hasta una linea que contenga el delimitador
• +body size=N stop="DELIMITADOR": el primer delimitador alcanzado (tamano o marcador) finaliza la lectura

Configuracion TOML

El formato de configuracion es TOML declarativo. Eleccion documentada en la ADR 0001:

• Por que TOML: legible por humanos, tipado nativo, estandar en el ecosistema Rust, sin indentacion significativa (a diferencia de YAML), mas expresivo que JSON para configuracion.
• Por que no YAML: la indentacion significativa es fuente de errores, tipos implicitos peligrosos (on/off -> booleano), especificacion compleja.
• Por que no JSON: sin comentarios, verboso, no disenado para configuracion humana.

La configuracion se valida al cargarse (fail-fast): sintaxis TOML, completitud de campos, coherencia de los placeholders, al menos un dominio, al menos una accion por dominio, valores enum no vacios.

Politica de dependencias

SSH-Frontière tiene una politica de cero dependencias no vitales. Cada crate externa debe estar justificada por una necesidad real.

Dependencias actuales

3 dependencias directas, ~20 dependencias transitivas:

Matriz de evaluacion

Antes de agregar una dependencia, se evalua segun 8 criterios ponderados (nota /5): licencia (eliminatorio), gobernanza (x3), comunidad (x2), frecuencia de actualizacion (x2), tamano (x3), dependencias transitivas (x3), funcionalidades (x2), no encerramiento (x1). Puntuacion minima: 3.5/5.

Auditoria

• cargo deny verifica las licencias y las vulnerabilidades conocidas
• cargo audit busca fallos en la base RustSec
• Fuentes autorizadas: crates.io unicamente

Como se diseno el proyecto

SSH-Frontière se desarrollo en fases sucesivas (1 a 9, con fases intermedias 2.5 y 5.5), pilotado por agentes Claude Code con una metodologia TDD sistematica:

El proyecto fue disenado por:

• Julien Garderon (BO): concepto, especificaciones funcionales, eleccion de Rust, nombre del proyecto
• Claude supervisor (PM/Tech Lead): analisis tecnico, arquitectura
• Agentes Claude Code: implementacion, tests, documentacion

Donde el humano y la maquina trabajan juntos, mejor, mas rapido, con mayor seguridad.