# Security Hardening Proposal: Centralizar y segmentar la sesión del bridge

## Decision

Debemos decidir cómo retirar la credencial ambiental `BRIDGE_TOKEN` sin cortar las aplicaciones del anfitrión, sus automatizaciones ni los proyectos vecinos que consumen el bridge.

## Executive Recommendation

Las opciones completas son: **Opción 1, compatibilidad endurecida**, que conserva la cabecera con controles adicionales; **Opción 2, migración gradual por capacidades**, que separa sesiones humanas y credenciales de servicio antes del corte; y **Opción 3, corte global inmediato**, que elimina la cabecera y rota de una vez.

Recomiendo la Opción 2 bajo las restricciones actuales. Es la única que reduce el radio de autoridad sin fingir que los consumidores heredados han desaparecido. No debemos iniciar su implementación hasta resolver los propietarios, HTTPS y la ventana operativa indicados al final.

## Evidence

Inspeccioné los middlewares y los consumidores que más influyen en el riesgo. La evidencia decisiva es que una misma credencial permite llegar tanto a lectura de estado como a archivos, deploy, secretos y acciones de sistema.

| Evidence | Finding or document | What it establishes |
| --- | --- | --- |
| `E001` | Frontera de autenticación del bridge | Cookie y cabecera conceden la misma autoridad general; las sesiones se pierden al reiniciar. |
| `E002`–`E006` | Clientes web internos | La migración es desigual: Codex Suite está en cookie, pero varias apps aún guardan o envían token. |
| `E007`–`E009` | Telegram y herramientas internas | Hay consumidores no navegador que no pueden depender de una cookie interactiva. |
| `E010` | Portal LAB de xzonassite | Existe al menos un consumidor externo real que envía `X-Bridge-Token`. |
| `E011` | Deep links de apps vecinas | ALimpiezas, Captajaus y Chatbot no transportan token; requieren sesión del navegador, no compatibilidad de cabecera propia. |
| `E012` | Topología :8095/Tailscale | `/apps` está en el bridge de EQUIPITELLO, no en el Docker remoto `.16`. |
| `E013` | Propagación de configuración | Hay una copia configurada como `XZ_IA_BRIDGE_TOKEN`; la rotación debe ser coordinada. |

## Current Design And Failure Mode

**Observed.** `BRIDGE_TOKEN` se carga al arrancar y sirve como secreto raíz. El usuario puede canjearlo por una cookie de 12 horas; el middleware también acepta directamente la cabecera heredada. La cookie es `HttpOnly` y `SameSite=Strict`, pero solo recibe `Secure` cuando la petición ya llega por HTTPS. El almacén de sesiones es un `Map` del proceso.

**Observed.** Al menos 12 frontends contienen rutas de transición o fallback; Telegram, dos utilidades y el portal LAB usan autenticación de máquina. Los endpoints protegidos abarcan capacidades con consecuencias muy distintas.

**Inferred.** El problema estructural no es únicamente dónde se guarda el token: es que una credencial compartida representa usuario, dispositivo, bot y servicio, sin identidad, alcance ni revocación individual. Una filtración conserva todo el radio de autoridad hasta la rotación global.

## Desired Invariants

- Ningún JavaScript servido conserva credenciales raíz en almacenamiento accesible al script.
- Toda sesión humana viaja por cookie `HttpOnly`, `Secure` y `SameSite=Strict` sobre HTTPS.
- Cada cliente no navegador tiene identidad, caducidad, revocación y capacidades mínimas propias.
- Una credencial de lectura no puede ejecutar sistema, escribir archivos, desplegar ni leer secretos.
- La rotación o revocación de un consumidor no obliga a interrumpir a todos los demás.
- El uso heredado se observa sin registrar secretos y llega a cero antes del corte.
- Reiniciar el bridge no invalida inesperadamente todas las sesiones válidas, salvo decisión explícita de seguridad.
- Ningún token se acepta en URL.

## Constraints And Non-Goals

- No alterar otros proyectos hasta que sus propietarios acepten una migración concreta.
- No sustituir Tailscale ni el launcher `/apps`.
- No exponer Codex App Server ni herramientas directamente a la red.
- No diseñar todavía SSO multiusuario ni una plataforma comercial completa.
- No afirmar que HTTPS existe: hoy el endpoint comprobado fue HTTP.
- Mantener rollback rápido durante cada fase.

## Before Architecture

[Diagrama actual](../diagrams/centralize-bridge-session-before.mmd)

El diagrama muestra una autoridad raíz compartida que converge en el mismo middleware. La cookie mejora la exposición en navegador, pero no cambia el alcance concedido ni resuelve identidad de servicios.

## Options

### Option 1: Compatibilidad endurecida

Conservaríamos `X-Bridge-Token`, rotaríamos la credencial y limitaríamos su admisión por red, cliente registrado y rate limit. Añadiríamos auditoría de uso y completaríamos el canje a cookie en las interfaces web. Es el camino de menor cambio para Telegram, scripts y el portal LAB.

[Diagrama posterior](../diagrams/centralize-bridge-session-compatibility-after.mmd)

| Change | Before | After | Security consequence | Cost |
| --- | --- | --- | --- | --- |
| Navegadores | Fallback heterogéneo | Cookie en todos los frontends | Menos exposición a XSS/localStorage | Migrar 10+ clientes |
| Cabecera | Aceptación global | Allowlist y auditoría | Reduce abuso accidental, no el secreto compartido | Configuración y observabilidad |
| Rotación | Global y manual | Global, coordinada | Expulsa copias antiguas | Posible interrupción |

Su ventaja es la compatibilidad y el rollback sencillo. Su límite es fundamental: una copia válida continúa teniendo autoridad amplia, y las allowlists basadas en red o nombre de cliente no sustituyen una credencial distinta. Debe verse como contención temporal, no como destino premium.

### Option 2: Migración gradual por capacidades

Separaríamos dos planos. Los navegadores usarían sesiones persistentes, revocables y enlazadas a HTTPS. Telegram, portal LAB, pruebas y futuras integraciones recibirían credenciales de servicio distintas, con capacidades explícitas y caducidad. Un adaptador heredado admitiría temporalmente `X-Bridge-Token`, registraría una huella no reversible del cliente y emitiría avisos de migración.

[Diagrama posterior](../diagrams/centralize-bridge-session-phased-session-after.mmd)

| Change | Before | After | Security consequence | Cost |
| --- | --- | --- | --- | --- |
| Autoridad | Token raíz ambiental | Sesiones y capacidades por consumidor | Limita el blast radius | Nuevo modelo de política |
| Sesiones | `Map` volátil | Store persistente y revocable | Reinicios previsibles, logout real | Estado cifrado o BD local |
| Servicios | Token compartido | Credencial individual | Rotación y auditoría aisladas | Migrar cada consumidor |
| Legacy | Sin fecha de retirada | Adaptador observado y deadline | Corte basado en evidencia | Dual stack temporal |

El coste principal no es latencia sino disciplina de política y migración. Una evaluación de capacidades por petición añade trabajo acotado en memoria; se debe medir con el workload real de SSE/chat y comandos. La persistencia introduce estado que hay que proteger y recuperar. A cambio, un fallo del portal LAB no compromete automáticamente Vault o System Manager.

El rollout es reversible mientras el adaptador exista: si un cliente falla, recupera temporalmente el camino heredado sin deshacer las sesiones nuevas. Tras una ventana sin uso heredado, se deshabilita la cabecera; el rollback posterior debe ser una bandera de emergencia con caducidad, no una restauración permanente.

### Option 3: Corte global inmediato

Eliminaríamos ya `X-Bridge-Token`, rotaríamos `BRIDGE_TOKEN` y exigiríamos cookie a navegadores y credenciales nuevas a servicios en una única ventana.

[Diagrama posterior](../diagrams/centralize-bridge-session-strict-session-after.mmd)

| Change | Before | After | Security consequence | Cost |
| --- | --- | --- | --- | --- |
| Legacy | Admitido | Rechazado | Elimina el bypass heredado | Rotura inmediata confirmada |
| Token raíz | Compartido | Rotado/no aceptado por APIs | Reduce exposición histórica | Reconfiguración coordinada |
| Operación | Dual | Un único modelo | Menor deuda final | Ventana y rollback complejos |

Es el estado final más limpio y puede ser apropiado tras un incidente activo. Sin embargo, la evidencia actual confirma consumidores que dejarían de funcionar, y aún no conocemos todos los externos. Aplicarlo ahora convertiría una mejora de seguridad en un incidente de disponibilidad y podría impulsar workarounds inseguros.

## Comparison

| Dimension | Option 1 | Option 2 | Option 3 |
| --- | --- | --- | --- |
| Security | Mejora parcial; autoridad compartida permanece | Mejora fuerte y segmentada | Mejora fuerte inmediata |
| Performance | Casi neutro; validar rate limit | Pequeña evaluación de política; medir SSE y API | Similar a Opción 2 sin dual stack |
| Memory | Casi neutro | Store de sesiones/políticas acotado | Store similar, sin adaptador |
| Reliability | Alta compatibilidad; rotación global frágil | Migración aislable y rollback por cliente | Riesgo alto de interrupción inicial |
| Operability | Baja al inicio; deuda persistente | Más inventario, métricas y gestión de claves | Operación final simple, cambio difícil |
| Migration | Menor | Media y por fases | Muy alta en una ventana |

Ninguna cifra de rendimiento o memoria fue medida. En la implementación seleccionada deberemos comparar p50/p95 de API, estabilidad SSE, RSS del proceso, persistencia/revocación y recuperación tras reinicio contra el bridge actual.

## Recommendation

Recomiendo la Opción 2. La evidencia de consumidores reales descarta un corte responsable hoy, mientras el alcance de Vault, deploy y sistema hace insuficiente conservar indefinidamente el token raíz. Cambiaría esta recomendación a Opción 3 solo ante compromiso activo confirmado y con autorización para asumir la interrupción; elegiría Opción 1 si no podemos proporcionar HTTPS ni modificar el consumidor `xzonassite` a medio plazo.

## Evidence Coverage And Residual Risk

| Evidence | Option 1 | Option 2 | Option 3 | Tactical protection still required |
| --- | --- | --- | --- | --- |
| `E001` — frontera global | Mitiga | Aborda | Aborda | CORS, origen, rate limit y CSP |
| `E002`–`E006` — frontends heredados | Mitiga | Aborda gradualmente | Aborda con rotura inicial | Eliminar localStorage y probar cada UI |
| `E007`–`E010` — clientes de servicio | No aborda alcance | Aborda por capacidades | Aborda tras migración simultánea | Inventario, propietarios y rotación |
| `E011` — deep links | No afectado | No afectado | No afectado salvo relogin | Evitar credenciales en URL |
| `E012` — Tailscale/HTTP | No aborda HTTPS | Requiere resolverlo | Requiere resolverlo | ACLs y no exponer 8095 a Internet |
| `E013` — copia de configuración | Mitiga con rotación | Aborda por credencial propia | Aborda con corte | Procedimiento de distribución segura |

Incluso con Opción 2 permanecen riesgos: XSS en otras apps del mismo origen, una CSP global permisiva fuera de Codex Suite, robo de sesión en el host, compromiso del store local y capacidades mal definidas. La segmentación reduce consecuencias, no sustituye hardening de cada interfaz.

## Migration And Rollout

No se autoriza aún un rollout. Si se selecciona Opción 2, el orden seguro será: congelar inventario; establecer HTTPS; diseñar store y capacidades; instrumentar uso heredado sin secretos; migrar frontends; emitir credenciales a servicios uno a uno; observar; rotar; deshabilitar cabecera; verificar; retirar adaptador. Cada fase conservará una bandera de rollback acotada y una prueba de aceptación.

## Validation Plan

- Matriz de todas las rutas con identidad/capacidad esperada y pruebas 401/403/200.
- Pruebas de login, logout, expiración, revocación, reinicio y fijación/robo de sesión.
- Pruebas de origen, CORS, CSRF, cookies `Secure` y ausencia de tokens en URL/logs/HTML/JS.
- Prueba funcional de cada frontend y PWA, incluido iPhone real por HTTPS/Tailscale.
- Pruebas específicas de Telegram, portal LAB, scripts y automatizaciones.
- Benchmark antes/después: latencia p50/p95, conexiones SSE concurrentes, RSS y recuperación.
- Simulación de rotación y rollback sin mostrar secretos.
- Ventana de telemetría acordada con cero uso heredado antes del corte.

## Implementation Work Packages

No se crea plan de implementación hasta seleccionar opción. Los paquetes previsibles son inventario/telemetría, HTTPS, store de sesión, política de capacidades, migración web, migración de servicios, rotación/corte y retirada del adaptador.

## Open Questions

1. ¿Qué scripts, bots o servicios fuera de la raíz de proyectos inspeccionada llaman al bridge?
2. ¿Deben Telegram y el portal LAB conservar todas sus acciones actuales o solo un subconjunto?
3. ¿Qué dispositivos/usuarios Tailscale están autorizados y hay Funnel activo?
4. ¿Preferimos Tailscale Serve, un reverse proxy HTTPS local u otra terminación?
5. ¿Cuánto tiempo deben sobrevivir las sesiones y deben persistir tras reinicio?
6. ¿Se acepta una ventana de relogin coordinada en iPhone y escritorio?
7. ¿Qué ventana sin uso heredado consideramos suficiente antes de cortar?