Para produção, defina `TR_SMOKE_BASE_URL=https://api.trustedrouter.com/v1` e
`TR_SMOKE_INTERNAL_TOKEN` se as rotas do gateway interno forem protegidas por token.

Defina as chaves locais de operador/provedor em:```text
/Users/jperla/claude/.quill_cloud_keys.private

O script de deploy também aceita aliases locais já usados em alguns arquivos de operadores: `CLAUDE_API_KEY` para Anthropic, `CHATGPT_API_KEY` para OpenAI e `STRIPE_KEY` para `STRIPE_SECRET_KEY`.

Vertex é diferente das outras plataformas de provedores: deploys de produção no GCP usam a conta de serviço do Cloud Run ou do Confidential Space e tokens de acesso Google de curta duração obtidos via metadata/ADC. Não coloque uma chave Vertex de longa duração neste arquivo para a rota Vertex pré-paga de primeira parte; conceda permissões de Vertex à conta de serviço de runtime.

## Licença

Business Source License 1.1. O código-fonte é público para que qualquer pessoa possa ler, compilar e verificar o código exato por trás das alegações de privacidade e atestação do TrustedRouter (https://trust.trustedrouter.com) — é para isso que ele está aqui. O uso não produtivo (revisão de segurança, auditoria, avaliação local) é gratuito. O uso em produção requer uma licença comercial da Lore Hex Corp:
[email protected]. Cada versão converte para a Apache License 2.0
quatro anos após a publicação. Código publicado antes de 3 de julho de 2026 permanece sob Apache-2.0.

## Padrões de Segurança

- O conteúdo de prompts e saídas nunca é armazenado.
- Os logs de uso contêm apenas metadados.
- As chaves de API são armazenadas como hashes SHA-256 com sal e IDs de chave opacos.
- As chaves de provedor BYOK enviadas pelo usuário são armazenadas como linhas de ciphertext com criptografia em envelope, não um objeto do Secret Manager por chave. Em produção, o Cloud KMS envolve a DEK por chave; referências externas `env://...` continuam suportadas para chaves gerenciadas por operadores.
- As autorizações do gateway incluem uma `byok_cache_key` não secreta para envelopes BYOK criptografados. Gateways atestados a usam para cache de chaves descriptografadas somente em memória com TTL curto; a rotação de BYOK altera a chave e o delete interrompe o retorno do envelope.
- As chaves brutas BYOK são entrada única; respostas públicas/do plano de controle expõem uma dica curta de primeiro/último caractere e metadados de referência criptografados, nunca texto simples.
- A configuração de produção falha de forma fechada sem um token de gateway interno, um segredo de webhook Stripe assinado e um backend de armazenamento que não seja somente memória.
- Os aplicativos do plano de controle em produção não registram `/chat/completions`, `/messages`, `/responses` ou `/embeddings`; esses pertencem ao plano de API atestado.
- O Sentry é exclusivo do plano de controle e remove corpos de requisição, cabeçalhos de autenticação, chaves de API, chaves BYOK, mensagens de prompt e texto de saída. Um limitador de inundação do Sentry no lado do cliente limita problemas repetidos por impressão digital e eventos totais por processo/janela, para que uma única integração ruidosa não possa consumir todo o orçamento de erros novamente.
- Nenhuma configuração do Sentry pertence ao enclave atestado.

## Observabilidade do Broadcast

Os proprietários de workspaces podem configurar destinos do Broadcast em `/v1/broadcast/destinations` ou no console, na seção Broadcast. Os destinos suportados são PostHog e webhooks JSON OTLP. O Broadcast é somente metadados por padrão: modelo, provedor, contagens de tokens, latência, custo, tipo de rota, região e metadados de rastreamento personalizados. O conteúdo de prompts/saídas é exportado apenas quando um destino habilita explicitamente `include_content`; esses destinos criptografados habilitados para conteúdo são retornados somente ao gateway atestado, não a respostas normais de gerenciamento. Entregas somente de metadados são gravadas primeiro em uma caixa de saída persistente do Broadcast e drenadas assincronamente por `/internal/broadcast/drain`, de modo que uma interrupção do PostHog/webhook não bloqueie a inferência nem perca metadados já liquidados na reinicialização do processo.

## Monitoramento Sintético

O TrustedRouter tem um plano separado de monitoramento sintético para uptime público. Os workers sintéticos são executados fora do enclave, enviam pequenas requisições reais para a API atestada pública e armazenam apenas metadados. Os aliases do modelo de monitor são:

- `trustedrouter/free`: pool gratuito estilo OpenRouter. Útil para usuários, não é um sinal de SLA.
- `trustedrouter/cheap`: pool pago mais barato com diversidade de provedores.
- `trustedrouter/eu`: pool de provedores focado na UE. Prefere provedores europeus, com regionalização na UE e voltados à privacidade, especialmente quando combinado com `https://api-europe-west4.quillrouter.com/v1`. Isso é uma política de roteamento, não uma garantia abrangente de residência de dados.
- `trustedrouter/monitor`: pool interno de uptime para verificações PONG e fallback. Fica visível no catálogo por transparência, mas a autorização exige a `TR_SYNTHETIC_MONITOR_API_KEY` configurada; chaves de API normais recebem 403.

Os workers devem ser executados a partir de `us-central1` e `europe-west4`, usando um workspace/chave dedicado `trustedrouter-synthetic-monitoring` com limites rígidos de gasto e recarga automática. Amostras brutas são linhas Bigtable somente anexação; as páginas públicas de status leem rollups compactos expostos em `/status`, `/status.json` e `/status/history?window=5m|24h|daily`. As gerações sintéticas usam o rótulo de aplicativo `TrustedRouter Synthetic` e são excluídas das análises de clientes/aplicativos.

A medição de provedores usa duas classes independentes de sondas:

- Sondas PONG curtas cobrem aleatoriamente todo o catálogo ativo e medem uptime, TTFB, TTFT e drift de API upstream.
- Um stream sustentado de 512 tokens cobre as 200 rotas de provedor/modelo mais importantes em rotação determinística a partir de `us-central1`. Ele mede tokens de saída por segundo após o primeiro token. É executado em um Cloud Run Job separado, de modo que streams lentos não podem atrasar as sondas de uptime. Falhas de sondas longas nunca contam contra o uptime do provedor ou alertas de drift de API.

O agendamento atual de dois minutos dá a cada rota sustentada cerca de 25 amostras por semana e 108 por 30 dias. O CI calcula uma estimativa de gasto de capacidade total a partir do catálogo ativo e falha se exceder o teto mensal revisado.

O status separa duas classes de SLO de serviço em vez de misturá-las com o comportamento do provedor upstream:

- `router_core`: API atestada acessível, autorização de chave funciona, candidatos a rota/fallback disponíveis e liquidação/reembolso durável.
- `control_plane`: painel, UI de faturamento, chaves, créditos, docs, trust e superfícies de status.

Watchdogs de deploy e alertas internos de taxa de queima usam `router_core` por padrão. Falhas somente de provedor são medidas por provedor em `/status` e `/leaderboard`; elas não consomem o orçamento de erros do router-core quando o fallback permanece disponível.

## Posicionamento Público

- Preços: o uso pré-pago e BYOK é rastreado em microdólares inteiros, não em dólares de ponto flutuante, para que custos minúsculos de tokens permaneçam auditáveis no ledger.
- Meta de uptime: `trustedrouter/auto` é um alias real de modelo de chat na inferência do plano de controle local/teste e alterna para o próximo provedor configurado em falhas de provedor upstream. `trustedrouter/eu` prefere o pool de provedores focado na UE, `trustedrouter/zdr` força um piso de provedor com retenção zero com Anthropic primeiro, e `trustedrouter/e2e` força rotas confidenciais + E2EE com Tinfoil primeiro. Requisições de chat também honram filtros de roteamento `models` e `provider` no estilo OpenRouter (`order`, `only`, `ignore`, `allow_fallbacks`, `min_privacy`, `data_collection` e `sort`) para que clientes possam solicitar cadeias de fallback explícitas ou preferências de provedor. `min_privacy="confidential"` é um requisito rígido de confidential-compute + E2EE no lado do provedor e falha de forma fechada; os aliases de valor de requisição `e2e` e `e2ee` selecionam o mesmo nível em vez de cair para uma rota mais fraca.
- Faturamento: créditos pré-pagos e BYOK primeiro; nenhuma assinatura é necessária.
- Confiança: open source hospedado, com o commit do código-fonte da API em execução, referência de imagem, digest de imagem e política de atestação publicados em `trust.trustedrouter.com`.
- Inscrição: o cadastro por e-mail cria uma chave de gerenciamento de uso único para o workspace.
- Wallet/cripto: o checkout com stablecoin é conectado pelo método de pagamento Crypto do Stripe Checkout quando solicitado. O Checkout por padrão com cartão permanece o caminho padrão.

## Meta de Escala

A meta é suportar escala do nível OpenRouter:

- 1 trilhão de tokens/dia, ou cerca de 11,6 milhões de tokens/segundo em média ao longo de um dia.
- 1-4 milhões de contas de desenvolvedores.
- 300+ modelos roteáveis ativamente.
- 60+ provedores.
- Overhead global de roteamento competitivo com roteadores implantados na borda.

A implantação de produção atual **ainda não** atende a essa meta. Ela executa o plano de controle em quatro regiões do GCP atrás de um LB global com NEGs Serverless por região, com três regiões de API atestada ativas até que pools regionais atestados adicionais sejam implantados. A capacidade escala horizontalmente à medida que mais pools atestados entram em operação; correção, confiança, faturamento e compatibilidade com SDKs estão em estado estacionário.

O volume de requisições depende fortemente do tamanho médio de geração. A 1 trilhão de tokens/dia:

| Tokens médios/requisição | Requisições/dia | Taxa média de requisições |
| ---: | ---: | ---: |
| 1.000 | 1,0B | 11,6k rps |
| 2.500 | 400M | 4,6k rps |
| 10.000 | 100M | 1,2k rps |

A arquitetura pode evoluir para essa escala, mas somente se o caminho crítico evitar gargalos globais por requisição. Isso significa frotas de gateway stateless regionais, pools de provedores regionais, leases de cota fragmentados, gravações de metadados somente anexação e agregação assíncrona.

## Latência Atual

Medida desta máquina de desenvolvimento para a API atestada centralizada do GCP em `us-central1` em 2 de maio de 2026:

| Sonda | p50 | p95 | Notas |
| --- | ---: | ---: | ---: |
| Rejeição não autenticada de `/v1/chat/completions` | 174 ms | 184 ms | Inclui DNS, TCP, TLS público, tratamento de requisição no enclave. |
| Conexão TCP | 55 ms | 59 ms | Caminho de rede até `us-central1` a partir desta máquina. |
| Handshake TLS completo | 112 ms | 124 ms | O certificado ACME público termina dentro do enclave. |
| `/attestation` | 1,06 s | 1,12 s | Inclui a geração do token de atestação do GCP, portanto não é representativo do overhead normal de roteamento. |

O overhead de rede centralizado é muito maior do que o overhead de borda relatado pelo OpenRouter, mas a latência do modelo geralmente domina requisições interativas. O primeiro passo de escala da produção deve ser multirregional em vez de construir uma borda global personalizada imediatamente.

## Formato de Escala Horizontal

O caminho de produção é projetado para escalar mantendo o gateway de prompt stateless:

- As instâncias de `api.trustedrouter.com` podem ser replicadas atrás de TCP passthrough. Elas autorizam, reservam e liquidam pelo plano de controle, mas os bytes de prompt nunca saem do caminho atestado.
- O Spanner armazena o estado do plano de controle e de faturamento com consistência forte: usuários, workspaces, chaves, metadados BYOK, idempotência de eventos de pagamento, saldos, agregados, reservas ativas e uma janela de auditoria terminal de requisições de 30 dias.
- O Bigtable armazena metadados de atividade de alto volume delimitados por workspace e data. Atividade e benchmarks de provedores retêm 30 dias, amostras sintéticas brutas retêm 14 dias e rollups compactos de status retêm 24 meses. Prompts, saídas e argumentos de chamadas de ferramentas não são armazenados.
- A verificação de chaves de API usa um hash de busca de alta entropia para leituras pontuais; não faz varredura de chaves.
- Os limites de taxa são aplicados antes dos handlers de rota e usam o armazenamento configurado, de modo que os contadores de produção são compartilhados entre instâncias do Cloud Run.

No tráfego na escala do OpenRouter, o próximo gargalo não é o binário do enclave; é o caminho síncrono de faturamento/autorização. A arquitetura precisa de reservas fragmentadas, clusters Bigtable regionais, limites de borda do Cloud Armor e múltiplas réplicas de gateway antes que o tráfego público possa aumentar.

## Plano Multirregional

Multirregional é viável preservando o limite de confiança, mas precisa ser feito com cuidado:

- Execute pools de gateway atestados quentes independentes em pelo menos `us-central1`, `us-east4` e `europe-west4`; depois Ásia assim que as três primeiras regiões estiverem estáveis.
- Mantenha as chaves privadas TLS dentro de cada workload regional do Confidential Space.
- Mude o ACME de TLS-ALPN-01 para DNS-01 ou outro fluxo de desafio que funcione com múltiplos endpoints regionais para o mesmo hostname. O fluxo atual TLS-ALPN-01 é suficiente para uma região, mas um registro DNS global pode rotear desafios para a réplica errada.
- Mantenha hostnames regionais como `api-us-central1.quillrouter.com`, `api-us-east4.quillrouter.com` e `api-europe-west4.quillrouter.com` para atestação determinística, testes de fumaça e failover de SDKs.
- Coloque `api.trustedrouter.com` atrás de DNS de latência/geo ou TCP passthrough que não termine TLS. O proxy orange-cloud do Cloudflare permanece incompatível com a alegação de confiança do caminho de prompt.
- Autorize por meio de leases de cota regionais, não por uma transação global síncrona do Spanner para cada requisição.
- Grave metadados de geração em clusters Bigtable regionais e agregue em visualizações globais de atividade assincronamente.
- Mantenha o roteamento de provedores regional, com circuit breakers por provedor, política de fallback e limites de taxa por provedor.

A regra de design principal: uma interrupção regional pode falhar de forma fechada ou rotear para outra região atestada, mas nunca deve degradar silenciosamente para um handler de prompt não atestado.

## Meta de Quatro Noves do Router-Core

A meta é um SLO interno, não um SLA contratual. 99,99% permite cerca de 52 minutos e 36 segundos de indisponibilidade por ano. O status público rotula esse número como meta até que existam pelo menos 30-60 dias de uptime medido de 99,99% do router-core.

Disponibilidade do router-core significa:

- TLS atestado acessível;
- validação de chave de API e autorização de gateway funcionando;
- candidatos a rota retornados e fallback capaz de escolher um provedor saudável;
- liquidação/reembolso durável ou reparável com segurança;
- nenhuma requisição de prompt cai jamais em um caminho não atestado.

Os caminhos de código que suportam esse roadmap hoje são:

- `/status.json` exporta `slo_classes.router_core`, `slo_classes.control_plane` e alertas de taxa de queima para janelas de 5m, 1h, 6h e 24h.
- O watchdog de deploy lê `router_core` por padrão, portanto interrupções somente de provedor não fazem rollback automático de um deploy do plano de controle.
- Espera-se que os SDKs tentem novamente falhas de conexão e 502/503/504 entre endpoints regionais atestados antes de expor a falha.
- As gravações de atividade no Bigtable são reparáveis a partir da caixa de saída durável de liquidação. A liquidação usa IDs de geração determinísticos, portanto novas tentativas sobrescrevem as mesmas linhas de índice e não podem cobrar em dobro nem duplicar atividade.

Antes de descrever quatro noves como disponibilidade medida e não meta, exija três regiões atestadas quentes no GCP, paging testado, testes de caos do router-core, deploys regionais em etapas com gates de rollback e pelo menos 30 dias de uptime do router-core medido em ou acima de 99,99%.

## Contrato do Gateway Interno

O plano de API atestado pode reservar e liquidar uso sem enviar conteúdo de prompt ou saída ao plano de controle:

- `POST /v1/internal/gateway/authorize`: valida o hash da chave de API, reserva créditos/limites de chave e retorna metadados de roteamento de provedor/BYOK, candidatos a rota derivados dos filtros de requisição `model`, `models` e `provider`, e endpoints regionais configurados.
- `POST /v1/internal/gateway/settle`: liquida o uso bem-sucedido e acrescenta linhas de atividade somente de metadados.
- `POST /v1/internal/gateway/refund`: libera reservas após falhas de provedor ou desconexões de clientes.

Defina `TR_INTERNAL_GATEWAY_TOKEN` fora do desenvolvimento local.

## Armazenamento em Produção

A produção 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