Para producción, define `TR_SMOKE_BASE_URL=https://api.trustedrouter.com/v1` y
`TR_SMOKE_INTERNAL_TOKEN` si las rutas internas de la pasarela están protegidas por token.

Define las claves locales de operador/proveedor en:```text
/Users/jperla/claude/.quill_cloud_keys.private

El script de despliegue también acepta alias locales ya utilizados en algunos archivos de operadores: `CLAUDE_API_KEY` para Anthropic, `CHATGPT_API_KEY` para OpenAI y `STRIPE_KEY` para `STRIPE_SECRET_KEY`.

Vertex es diferente de las otras plataformas de proveedores: los despliegues de producción en GCP usan la cuenta de servicio de Cloud Run o Confidential Space y tokens de acceso de Google de corta duración provenientes de metadata/ADC. No pongas una clave Vertex de larga duración en este archivo para la ruta Vertex prepagada de primera parte; concédele permisos de Vertex a la cuenta de servicio en tiempo de ejecución.

## Licencia

Business Source License 1.1. El código fuente es público para que cualquiera pueda leer, compilar y verificar el código exacto detrás de las afirmaciones de privacidad y atestación de TrustedRouter (https://trust.trustedrouter.com); para eso está aquí. El uso no productivo (revisión de seguridad, auditoría, evaluación local) es gratuito. El uso en producción requiere una licencia comercial de Lore Hex Corp: [email protected]. Cada versión se convierte a la Licencia Apache 2.0 cuatro años después de su publicación. El código publicado antes del 3 de julio de 2026 permanece bajo Apache-2.0.

## Valores Predeterminados de Seguridad

- El contenido de las indicaciones y las respuestas nunca se almacena.
- Los registros de uso contienen solo metadatos.
- Las claves API se almacenan como hash SHA-256 con sal e identificadores de clave opacos.
- Las claves de proveedor BYOK enviadas por el usuario se almacenan como filas de texto cifrado con cifrado en sobre, no un objeto de Secret Manager por clave. En producción, Cloud KMS envuelve el DEK por clave; las referencias externas `env://...` siguen siendo compatibles para claves gestionadas por el operador.
- Las autorizaciones del gateway incluyen una `byok_cache_key` no secreta para sobres BYOK cifrados. Los gateways atestados la usan para almacenamiento en caché de claves descifradas solo en memoria y con TTL corto; la rotación de BYOK cambia la clave y el borrado deja de devolver el sobre.
- Las claves raw BYOK son de entrada única; las respuestas públicas/del plano de control exponen una breve pista de primera/última letra de la clave y metadatos de referencia cifrados, nunca texto plano.
- La configuración de producción falla de forma segura sin un token interno de gateway, un secreto de webhook de Stripe firmado y un backend de almacenamiento que no sea solo memoria.
- Las aplicaciones del plano de control en producción no registran `/chat/completions`, `/messages`, `/responses` ni `/embeddings`; esas rutas pertenecen al plano de API atestada.
- Sentry es exclusivo del plano de control y depura los cuerpos de las solicitudes, los encabezados de autenticación, las claves API, las claves BYOK, los mensajes de las indicaciones y el texto de salida. Una compuerta de inundación de Sentry en el cliente limita los problemas repetidos por huella y el total de eventos por proceso/ventana, de modo que una integración ruidosa no pueda volver a consumir todo el presupuesto de errores.
- Ninguna configuración de Sentry pertenece al enclave atestado.

## Observabilidad de Broadcast

Los propietarios de espacios de trabajo pueden configurar destinos de Broadcast en `/v1/broadcast/destinations` o en la consola, en Broadcast. Los destinos compatibles son PostHog y webhooks JSON OTLP. Broadcast es solo de metadatos por defecto: modelo, proveedor, conteos de tokens, latencia, costo, tipo de ruta, región y metadatos de traza personalizados. El contenido de indicaciones/respuestas se exporta solo cuando un destino habilita explícitamente `include_content`; esos destinos cifrados habilitados para contenido se devuelven únicamente al gateway atestado, no a las respuestas normales de gestión. Las entregas solo de metadatos se escriben primero en un outbox persistente de Broadcast y se drenan asincrónicamente mediante `/internal/broadcast/drain`, de modo que una caída de PostHog/webhook no bloquee la inferencia ni pierda metadatos ya liquidados al reiniciar el proceso.

## Monitoreo Sintético

TrustedRouter tiene un plano separado de monitoreo sintético para el tiempo de actividad público. Los trabajadores sintéticos se ejecutan fuera del enclave, envían pequeñas solicitudes reales a la API pública atestada y almacenan solo metadatos. Los alias de modelo del monitor son:

- `trustedrouter/free`: grupo gratuito estilo OpenRouter. Útil para usuarios, no es una señal de SLA.
- `trustedrouter/cheap`: el grupo de pago más barato con diversidad de proveedores.
- `trustedrouter/eu`: grupo de proveedores centrado en la UE. Prefiere proveedores europeos, con capacidad de región en la UE y centrados en la privacidad, especialmente cuando se combina con `https://api-europe-west4.quillrouter.com/v1`. Esto es una política de enrutamiento, no una garantía general de residencia de datos.
- `trustedrouter/monitor`: grupo interno de tiempo de actividad para comprobaciones PONG y de respaldo. Es visible en el catálogo por transparencia, pero la autorización requiere la `TR_SYNTHETIC_MONITOR_API_KEY` configurada; las claves API normales reciben 403.

Los trabajadores deberían ejecutarse desde `us-central1` y `europe-west4`, usando un espacio de trabajo/clave dedicado `trustedrouter-synthetic-monitoring` con límites de gasto estrictos y recarga automática. Las muestras crudas son filas append-only en Bigtable; las páginas públicas de estado leen resúmenes compactos expuestos en `/status`, `/status.json` y `/status/history?window=5m|24h|daily`. Las generaciones sintéticas usan la etiqueta de aplicación `TrustedRouter Synthetic` y se excluyen de las analíticas de clientes/aplicaciones.

La medición de proveedores usa dos clases independientes de sondas:

- Las sondas PONG cortas cubren aleatoriamente todo el catálogo activo y miden tiempo de actividad, TTFB, TTFT y desviación de la API ascendente.
- Un flujo sostenido de 512 tokens cubre las 200 rutas de proveedor/modelo más importantes en rotación determinista desde `us-central1`. Mide tokens de salida por segundo después del primer token. Se ejecuta en un Cloud Run Job separado, por lo que los flujos lentos no pueden retrasar las sondas de tiempo de actividad. Las fallas de sondas largas nunca cuentan contra el tiempo de actividad del proveedor ni contra las alertas de desviación de API.

El horario actual de dos minutos le da a cada ruta sostenida unas 25 muestras por semana y 108 por cada 30 días. CI calcula una estimación de gasto de capacidad completa a partir del catálogo en vivo y falla si supera el techo mensual revisado.

El estado separa dos clases de SLO de servicio en lugar de mezclarlas con el comportamiento del proveedor ascendente:

- `router_core`: la API atestada es alcanzable, la autorización de claves funciona, los candidatos de ruta/respaldo están disponibles y el cierre/liquidación/reembolso es duradero.
- `control_plane`: panel de control, interfaz de facturación, claves, créditos, documentación, confianza y superficies de estado.

Los watchdogs de despliegue y las alertas internas de tasa de consumo usan `router_core` por defecto. Las fallas solo de proveedores se miden por proveedor en `/status` y `/leaderboard`; no consumen el presupuesto de errores de router-core cuando el respaldo sigue disponible.

## Posicionamiento Público

- Precios: el uso prepagado y BYOK se registra en microdólares enteros, no en dólares de punto flotante, de modo que los costos diminutos de tokens sigan siendo auditables en el libro mayor.
- Objetivo de tiempo de actividad: `trustedrouter/auto` es un alias real de modelo de chat en la inferencia local/de prueba del plano de control y pasa al siguiente proveedor configurado cuando fallan los proveedores ascendentes. `trustedrouter/eu` prefiere el grupo de proveedores centrado en la UE, `trustedrouter/zdr` fuerza un piso de proveedor sin retención con Anthropic primero, y `trustedrouter/e2e` fuerza rutas confidenciales + E2EE con Tinfoil primero. Las solicitudes de chat también respetan los filtros de enrutamiento `models` y `provider` estilo OpenRouter (`order`, `only`, `ignore`, `allow_fallbacks`, `min_privacy`, `data_collection` y `sort`) para que los clientes puedan solicitar cadenas de respaldo explícitas o preferencias de proveedor. `min_privacy="confidential"` es un requisito estricto de cómputo confidencial + E2EE del lado del proveedor y falla de forma segura; los alias de valor de solicitud `e2e` y `e2ee` seleccionan el mismo nivel en lugar de recurrir a una ruta más débil.
- Facturación: créditos prepagados y BYOK primero; no se requiere suscripción.
- Confianza: código abierto alojado, con el commit del código fuente de la API en ejecución, la referencia de la imagen, el digest de la imagen y la política de atestación publicados en `trust.trustedrouter.com`.
- Registro: el registro por correo electrónico crea una clave de gestión de un solo uso para el espacio de trabajo.
- Wallet/cripto: el pago con stablecoin se conecta a través del método de pago Crypto de Stripe Checkout cuando se solicita. El Checkout con tarjeta/por defecto sigue siendo el camino estándar.

## Objetivo de Escala

La meta es soportar una escala de clase OpenRouter:

- 1 billón de tokens al día, o unos 11,6 millones de tokens por segundo en promedio diario.
- 1-4 millones de cuentas de desarrolladores.
- 300+ modelos enrutablemente activos.
- 60+ proveedores.
- Sobrecarga de enrutamiento global competitiva con routers desplegados en el borde.

El despliegue de producción actual **no** cumple aún ese objetivo. Ejecuta el plano de control en cuatro regiones de GCP detrás de un LB global con Serverless NEG por región, con tres regiones de API atestada en vivo hasta que se desplieguen grupos regionales atestados adicionales. La capacidad escala horizontalmente a medida que más grupos atestados entran en línea; la corrección, la confianza, la facturación y la compatibilidad con SDK están en estado estacionario.

El volumen de solicitudes depende en gran medida del tamaño promedio de generación. A 1 billón de tokens al día:

| Tokens promedio por solicitud | Solicitudes por día | Tasa promedio de solicitudes |
| ---: | ---: | ---: |
| 1,000 | 1.0B | 11.6k rps |
| 2,500 | 400M | 4.6k rps |
| 10,000 | 100M | 1.2k rps |

La arquitectura puede evolucionar a esta escala, pero solo si la ruta caliente evita cuellos de botella globales por solicitud. Eso significa flotas de gateway regionales sin estado, grupos de proveedores regionales, arrendamientos de cuota fragmentados, escrituras de metadatos append-only y agregación asíncrona.

## Latencia Actual

Medida desde esta máquina de desarrollo hasta la API atestada centralizada de GCP en `us-central1` el 2 de mayo de 2026:

| Sonda | p50 | p95 | Notas |
| --- | ---: | ---: | --- |
| Rechazo no autenticado de `/v1/chat/completions` | 174 ms | 184 ms | Incluye DNS, TCP, TLS público y manejo de solicitudes del enclave. |
| Conexión TCP | 55 ms | 59 ms | Ruta de red a `us-central1` desde esta máquina. |
| Handshake TLS completo | 112 ms | 124 ms | El certificado público ACME termina dentro del enclave. |
| `/attestation` | 1.06 s | 1.12 s | Incluye la generación del token de atestación de GCP, por lo que no es representativo de la sobrecarga normal de enrutamiento. |

La sobrecarga de red centralizada es mucho mayor que la sobrecarga de borde reportada por OpenRouter, pero la latencia del modelo suele dominar las solicitudes interactivas. El primer paso de escalado de producción debería ser multirregional en lugar de construir un borde global personalizado de inmediato.

## Forma de Escala Horizontal

La ruta de producción está diseñada para escalar manteniendo el gateway de indicaciones sin estado:

- Las instancias de `api.trustedrouter.com` pueden replicarse detrás de TCP passthrough. Autorizan, reservan y liquidan a través del plano de control, pero los bytes de las indicaciones nunca salen de la ruta atestada.
- Spanner almacena estado fuertemente consistente del plano de control y facturación: usuarios, espacios de trabajo, claves, metadatos BYOK, idempotencia de eventos de pago, saldos, agregados, reservas activas y una ventana de auditoría terminal de solicitudes de 30 días.
- Bigtable almacena metadatos de actividad de alto volumen limitados, con clave por espacio de trabajo y fecha. La actividad y los benchmarks de proveedores retienen 30 días, las muestras sintéticas crudas retienen 14 días y los resúmenes compactos de estado retienen 24 meses. Las indicaciones, salidas y argumentos de llamadas a herramientas no se almacenan.
- La verificación de claves API usa un hash de búsqueda de alta entropía para lecturas puntuales; no escanea claves.
- Los límites de tasa se aplican antes de los manejadores de ruta y usan el almacén configurado, de modo que los contadores de producción se comparten entre las instancias de Cloud Run.

A tráfico de escala OpenRouter, el siguiente cuello de botella no es el binario del enclave; es la ruta síncrona de facturación/autorización. La arquitectura necesita reservas fragmentadas, clústeres regionales de Bigtable, límites de borde de Cloud Armor y múltiples réplicas de gateway antes de permitir que el tráfico público aumente.

## Plan Multirregional

Lo multirregional es factible preservando el límite de confianza, pero debe hacerse con cuidado:

- Ejecutar grupos de gateway atestados cálidos independientes en al menos `us-central1`, `us-east4` y `europe-west4`, y luego Asia una vez que las tres primeras regiones sean aburridas.
- Mantener las claves privadas TLS dentro de cada carga de trabajo regional de Confidential Space.
- Mover ACME de TLS-ALPN-01 a DNS-01 u otro flujo de desafío que funcione con múltiples endpoints regionales para el mismo nombre de host. El flujo actual TLS-ALPN-01 está bien para una región, pero un registro DNS global puede enrutar los desafíos a la réplica equivocada.
- Mantener nombres de host regionales como `api-us-central1.quillrouter.com`, `api-us-east4.quillrouter.com` y `api-europe-west4.quillrouter.com` para atestación determinista, pruebas de humo y conmutación por error del SDK.
- Poner `api.trustedrouter.com` detrás de DNS de latencia/geo o TCP passthrough que no termine TLS. El proxy orange-cloud de Cloudflare sigue siendo incompatible con la afirmación de confianza de la ruta de indicaciones.
- Autorizar mediante arrendamientos de cuota regionales, no una transacción global síncrona de Spanner por cada solicitud.
- Escribir metadatos de generación en clústeres regionales de Bigtable y luego agregarlos en vistas globales de actividad de forma asíncrona.
- Mantener el enrutamiento de proveedores regional, con interruptores de circuito específicos por proveedor, política de respaldo y límites de tasa por proveedor.

La regla clave de diseño: una caída regional puede fallar de forma cerrada o enrutar a otra región atestada, pero nunca debe degradarse silenciosamente a un manejador de indicaciones no atestado.

## Objetivo de Cuatro Nueves de Router-Core

El objetivo es un SLO interno, no un SLA contractual. 99.99% permite unos 52 minutos y 36 segundos de inactividad al año. El estado público etiqueta este número como un objetivo hasta que existan al menos 30-60 días de tiempo de actividad de router-core medido al 99.99%.

La disponibilidad de router-core significa:

- el TLS atestado es alcanzable;
- la validación de claves API y la autorización del gateway funcionan;
- se devuelven candidatos de ruta y el respaldo puede elegir un proveedor saludable;
- la liquidación/reembolso es duradera o reparable de forma segura;
- ninguna solicitud de indicación cae jamás en una ruta no atestada.

Las rutas de código que respaldan esta hoja de ruta hoy son:

- `/status.json` exporta `slo_classes.router_core`, `slo_classes.control_plane` y alertas de tasa de consumo para ventanas de 5m, 1h, 6h y 24h.
- El watchdog de despliegue lee `router_core` por defecto, de modo que las caídas solo de proveedores no revierten automáticamente un despliegue del plano de control.
- Se espera que los SDK reintenten fallas de conexión y 502/503/504 entre endpoints regionales atestados antes de informar la falla.
- Las escrituras de actividad en Bigtable son reparables desde el outbox duradero de liquidación. La liquidación usa IDs de generación deterministas, por lo que los reintentos sobrescriben las mismas filas de índice y no pueden cobrar dos veces ni duplicar actividad.

Antes de describir los cuatro nueves como disponibilidad medida en lugar de un objetivo, se requieren tres regiones atestadas cálidas de GCP, paginación probada, pruebas de caos de router-core, despliegues regionales por etapas con compuertas de reversión y al menos 30 días de tiempo de actividad de router-core medido al 99.99% o más.

## Contrato Interno de Gateway

El plano de API atestada puede reservar y liquidar uso sin enviar contenido de indicaciones o salidas al plano de control:

- `POST /v1/internal/gateway/authorize`: valida el hash de la clave API, reserva créditos/límites de clave y devuelve metadatos de enrutamiento de proveedor/BYOK, candidatos de ruta derivados de los filtros de solicitud `model`, `models` y `provider`, y endpoints regionales configurados.
- `POST /v1/internal/gateway/settle`: liquida el uso exitoso y agrega filas de actividad solo de metadatos.
- `POST /v1/internal/gateway/refund`: libera reservas después de fallas de proveedor o desconexiones de cliente.

Establece `TR_INTERNAL_GATEWAY_TOKEN` fuera del desarrollo local.

## Almacenamiento en Producción

La producción usa:```text
TR_STORAGE_BACKEND=spanner-bigtable
TR_SPANNER_INSTANCE_ID=trusted-router
TR_SPANNER_DATABASE_ID=trusted-router
TR_BIGTABLE_INSTANCE_ID=trusted-router-logs
TR_BIGTABLE_GENERATION_TABLE=trustedrouter-generations