lore-hex/quill-routerRepositório TrustedRouter.com para proxy seguro de LLMs.
# TrustedRouter
[](https://github.com/Lore-Hex/quill-router/actions/workflows/ci.yml)
[](https://github.com/Lore-Hex/quill-router/actions/workflows/deploy.yml)
[](https://github.com/Lore-Hex/quill-router/actions/workflows/prod-smoke.yml)
[](https://github.com/Lore-Hex/quill-router/actions/workflows/trust-drift.yml)
[](https://status.trustedrouter.com)
[](https://trust.trustedrouter.com)
[](https://www.npmjs.com/package/@lore-hex/trusted-router)
[](https://pypi.org/project/trusted-router-py/)
[](LICENSE)
# LLMs com criptografia de ponta a ponta. Uma API. Privacidade com prova.
Pare de se preocupar com quem pode ver seus prompts. Diga ao seu agente de programação para migrar
seu projeto, escolha o nível de privacidade que deseja, escolha um modelo, insira uma
chave — pronto. A mesma API, mais de 30 modelos, uma única chave. O gateway roda em enclaves
de hardware e você pode verificar criptograficamente que ele nunca registra seus dados.
### Migre seu projeto com um único prompt
Cole isto no Codex, Claude Code ou Cursor — ele faz a migração para você:
```text
Migrate this project to TrustedRouter, a privacy-first LLM router
(https://trustedrouter.com). Repoint my LLM client to base_url
"https://api.trustedrouter.com/v1" (or "https://api.trustedrouter.com" for the
Anthropic SDK), read the key from the TRUSTEDROUTER_API_KEY env var, and keep
all my existing calls working.
For a hard provider-side confidential-compute and end-to-end-encryption
requirement, add {"provider": {"min_privacy": "confidential"}}. TrustedRouter
fails closed when the selected model or provider cannot satisfy both controls.
Then tell me to sign up at trustedrouter.com, add a card, and paste my sk-tr
key into TRUSTEDROUTER_API_KEY.
```
Em seguida:
1. **Escolha seu nível de privacidade ou região** — use
`{"provider": {"min_privacy": "zdr"}}` para um piso rígido de retenção zero, ou
`{"provider": {"min_privacy": "confidential"}}` para o piso mais forte de
computação confidencial + E2EE. Os aliases convenientes `trustedrouter/zdr` e
`trustedrouter/e2e` (`trustedrouter/confidential`) selecionam esses
pools. Use `trustedrouter/eu` com
`https://api-europe-west4.quillrouter.com/v1` para roteamento focado na UE.
2. **Escolha um modelo** — qualquer um entre centenas, ou `trustedrouter/auto` para fallback
automático quando a amplitude de provedores importa mais do que o filtro de privacidade
mais estrito.
3. **Cadastre-se, adicione um cartão, obtenha sua chave** em https://trustedrouter.com.
4. **Publique** — seus prompts agora passam por um caminho que você pode verificar.
<details>
<summary>Prefere configurar manualmente?</summary>
```bash
# Codex
export OPENAI_BASE_URL="https://api.trustedrouter.com/v1"
export OPENAI_API_KEY="sk-tr-v1-..."
# Claude Code
export ANTHROPIC_BASE_URL="https://api.trustedrouter.com"
export ANTHROPIC_API_KEY="sk-tr-v1-..."
```
```python
# Any OpenAI SDK
client = OpenAI(base_url="https://api.trustedrouter.com/v1", api_key="sk-tr-v1-...")
```
</details>
- **Obtenha uma chave / pague-me:** https://trustedrouter.com
- **Experimente primeiro (sem cadastro):** https://trustedrouter.com/chat
- **Os detalhes técnicos (para os nerds):** https://trustedrouter.com/security
- **Gerar imagens:** [docs/image-generation.md](https://github.com/lore-hex/quill-router/blob/main/docs/image-generation.md)
- **Gerar vídeo:** [docs/video-generation.md](https://github.com/lore-hex/quill-router/blob/main/docs/video-generation.md)
- **Por que o construímos:** https://jperla.com/blog/attestation-is-all-you-need
---
<details>
<summary><strong>Para os nerds: como a privacidade é comprovável</strong></summary>
O gateway do TrustedRouter é executado dentro do GCP Confidential Space. A plataforma assina
uma medição do contêiner em execução. Verifique essa evidência assinada e compare
seu digest de imagem com a medição de lançamento publicada. A revisão do código-fonte e a
proveniência da build de lançamento estabelecem o que essa imagem medida faz; um digest
correspondente por si só não prova a ausência de bugs ou de registro de logs.
Inspecione a evidência do GCP, sem conta:
```bash
NONCE=$(openssl rand -hex 16)
curl --fail --silent --show-error \
"https://api-us-central1.quillrouter.com/attestation?nonce=$NONCE" \
--output attestation.jwt
# GCP returns a raw Google-signed JWT, not a JSON response.
# Decoded claims include eat_nonce and submods.container.image_digest.
# GCP evidence has no pcrs field; PCRs belong to AWS Nitro evidence.
```
Salvar ou decodificar um JWT **não é verificação**. Use o
[verificador de atestação](https://github.com/Lore-Hex/quill-cloud-proxy/blob/main/tools/verify-attestation.py)
a partir de um checkout revisado do `quill-cloud-proxy` para verificar o emissor/assinatura,
nonce recente, vinculação de certificado/exportador TLS e a medição de release esperada.
Para um endpoint GCP, execute a partir desse checkout:
```bash
DIGESTS=$(curl --fail --silent --show-error \
https://trust.trustedrouter.com/trust/accepted-image-digests-gcp.txt)
test -n "$DIGESTS" && uv run --script tools/verify-attestation.py \
--api-host api-us-central1.quillrouter.com --expect-digest "$DIGESTS"
```
O verificador obtém evidências novas na conexão TLS que verifica. Essa
verificação não atesta uma conexão `curl` ou SDK posterior e separada. Estes exemplos
usam o hostname publicado do GCP US Central para selecionar o formato de evidência do GCP. O endpoint
global pode selecionar outra nuvem; use sua política de verificação específica da nuvem
e as medições de [the trust site](https://trust.trustedrouter.com/).
| | modelo de confiança |
|---|---|
| OpenRouter, provedores hospedados | "Não registramos logs." Uma política que você não pode verificar. |
| Portkey, Cloudflare AI Gateway | Registre tudo para observabilidade. |
| LiteLLM | Auto-hospedado, mas o proxy em execução não é verificado. |
| **TrustedRouter** | **Código aberto + atestação de hardware. Verifique o caminho do código; ele não registra nada.** |
Escopo honesto: a atestação prova que o binário em execução é o binário publicado em
hardware que você pode desafiar com um nonce. Ela não derrota um estado-nação com
acesso físico ao host, e não prova que o binário de código aberto está livre de bugs.
A âncora de confiança é a cadeia de atestação com suporte de hardware do Google Confidential Computing. Os provedores upstream tratam os prompts de acordo com
suas próprias políticas — a postura de cada provedor é publicada nas páginas dos modelos.
</details>
---
## Estrutura do repositório
Este repositório implementa o contrato do plano de controle: cobertura de rotas, gerenciamento de autenticação/chaves,
semântica do livro-razão de cobrança, metadados de uso, proibições de registro de prompts/saídas,
scrubbers do Sentry e abstrações de provedores. A implementação do gateway atestado
fica em `quill-cloud-proxy`.
Limite de confiança: `api.trustedrouter.com` é o caminho de prompt atestado e deve
terminar o TLS dentro do Confidential Space. `trustedrouter.com` é o plano de
controle e nunca deve servir um fallback de inferência em produção.
`api.quillrouter.com` permanece um alias permanente funcional (mesmo gateway atestado
e certificado), para que as integrações existentes continuem funcionando sem migração.
## Local
```bash
uv sync
uv run pytest
uv run uvicorn trusted_router.main:app --reload
```
Smoke de ponta a ponta contra uma instância em execução:
```bash
TR_SMOKE_BASE_URL=http://127.0.0.1:18080/v1 uv run python scripts/smoke_e2e.py
```
Para produção, defina `TR_SMOKE_BASE_URL=https://api.trustedrouter.com/v1` e
`TR_SMOKE_INTERNAL_TOKEN` se as rotas internas do gateway estiverem protegidas por token.
Defina as chaves locais de operador/provedor em:
```text
/Users/jperla/claude/.quill_cloud_keys.private
```
Esse arquivo nunca é commitado. Espera-se que esteja no estilo dotenv:
```text
ANTHROPIC_API_KEY=...
OPENAI_API_KEY=...
GEMINI_API_KEY=...
CEREBRAS_API_KEY=...
DEEPSEEK_API_KEY=...
MISTRAL_API_KEY=...
STRIPE_SECRET_KEY=...
STRIPE_WEBHOOK_SECRET=...
SENTRY_DSN=...
```
O script de deploy também aceita aliases locais já usados em alguns arquivos de operador: `CLAUDE_API_KEY` para Anthropic, `CHATGPT_API_KEY` para OpenAI e `STRIPE_KEY` para `STRIPE_SECRET_KEY`.
O Vertex é diferente das outras plataformas de provedores: implantações de produção no GCP usam a conta de serviço do Cloud Run ou do Confidential Space e tokens de acesso do Google de curta duração provenientes de metadata/ADC. Não coloque uma chave Vertex de longa duração neste arquivo para a rota Vertex pré-paga de primeira parte; em vez disso, conceda permissões do 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 declaraçõ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 produtivo 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. O código publicado antes de 3 de julho de 2026 permanece Apache-2.0.
## Padrões de Segurança
- O conteúdo de prompts e saídas nunca é registrado em log. A inferência síncrona e em streaming comum não o retém. A Batch API opcional retém temporariamente artefatos criptografados pelo enclave por até 30 dias.
- Os logs de uso contêm apenas metadados.
- As chaves de API são armazenadas como hashes SHA-256 com salt e IDs de chave opacos.
- As chaves de provedor BYOK enviadas pelo usuário são armazenadas como linhas de texto cifrado com criptografia de envelope, não como 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 pelo operador.
- As autorizações do gateway incluem um `byok_cache_key` não secreto para envelopes BYOK criptografados. Gateways atestados o utilizam para cache de chaves descriptografadas apenas em memória, com TTL curto; a rotação de BYOK altera a chave e a exclusão interrompe o retorno do envelope.
- As chaves BYOK brutas são apenas de entrada única; as respostas públicas/do plano de controle expõem apenas uma dica curta dos primeiros/últimos caracteres da chave e metadados de referência criptografados, nunca o texto simples.
- A configuração de produção falha de forma fechada sem um token de gateway interno, um segredo de webhook do Stripe assinado e um backend de armazenamento não volátil.
- Os aplicativos do plano de controle de 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 flood do Sentry no lado do cliente limita problemas repetidos por fingerprint e o total de eventos 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 de Broadcast
Os proprietários de workspace podem configurar destinos de Broadcast em `/v1/broadcast/destinations` ou no console em Broadcast. Os destinos suportados são PostHog e webhooks OTLP JSON. O Broadcast é apenas de metadados por padrão: modelo, provedor, contagens de tokens, latência, custo, tipo de rota, região e metadados de trace personalizados. O conteúdo de prompt/saída é exportado apenas quando um destino habilita explicitamente `include_content`; esses destinos criptografados com conteúdo habilitado são retornados apenas ao gateway atestado, não às respostas normais de gerenciamento. As entregas apenas de metadados são gravadas primeiro em uma outbox persistente de Broadcast e drenadas de forma assíncrona por `/internal/broadcast/drain`, de modo que uma indisponibilidade do PostHog/webhook não bloqueia a inferência nem perde metadados já liquidados na reinicialização do processo.
## Camadas de roteamento fixas
Esses aliases usam um pool de modelos explicitamente ordenado: o primeiro membro é o preferido e os demais são fallbacks. Eles executam um modelo por tentativa, sem síntese, orquestração ou piso de privacidade implícito. Defina `provider.min_privacy` explicitamente quando necessário. O catálogo ativo em `/v1/models` publica cada pool em `auto_candidates`.
- `trustedrouter/frontier`: pool fixo de modelos frontier.
- `trustedrouter/advanced`: pool fixo de modelos advanced.
- `trustedrouter/professional`: pool fixo de modelos professional.
- `trustedrouter/efficient`: pool fixo de modelos efficient.
## Monitoramento Sintético
O TrustedRouter possui um plano de monitoramento sintético separado para uptime público.
Workers sintéticos são executados fora do enclave, enviam pequenas requisições reais para a
API pública atestada e armazenam apenas metadados. Os aliases de modelo do monitor são:
- `trustedrouter/free`: pool gratuito no 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. Ele prefere provedores europeus,
regionalizáveis na UE e voltados à privacidade, especialmente quando combinado com
`https://api-europe-west4.quillrouter.com/v1`. Esta é 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 de fallback.
Ele é 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. As amostras brutas são linhas append-only no Bigtable; as páginas de status públicas
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 aplicação `TrustedRouter Synthetic` e são excluídas das análises
de clientes/aplicações.
Toda invocação do monitor também faz uma conclusão de chat com `stream: true` e falha
a menos que receba um evento de dados SSE, um chunk terminal e `[DONE]`. O
job recorrente Stage D adiciona `--expect-stage-d`, depois consulta a autorização tipada
daquela requisição e exige um `stage_d_boot_kid` vinculado mais
`heartbeat_seq > 0`. Seu workspace é intencionalmente separado: provisione-o
com `scripts/provision_stage_d_probe_workspace.py` e adicione seu id a
`TR_STAGE_D_PILOT_WORKSPACE_IDS`. A chave deve ser uma
chave local tipada com capacidade de heartbeat; o deploy a lê de
`trustedrouter-stage-d-probe-api-key` e usa `trustedrouter/cheap` para que seja
independente da chave comum exclusiva do monitor. A implantação normal deixa a elegibilidade do Stage D
desativada, portanto criar a chave sozinha não habilita o Stage D.
A medição de provedores usa duas classes de sondagem independentes:
- Sondas PONG curtas cobrem aleatoriamente todo o catálogo ativo e medem uptime,
TTFB, TTFT e desvio da API upstream.
- Um stream sustentado de 512 tokens cobre as 200 rotas 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. Ele é executado em um Cloud Run Job separado,
para que streams lentos não atrasem as sondas de uptime. Falhas de sondagem longa nunca contam
contra o uptime do provedor ou alertas de desvio de API.
O cronograma atual de dois minutos dá a cada rota sustentada cerca de 25 amostras por
semana e 108 por 30 dias. A CI calcula uma estimativa de gasto no limite máximo 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 de rota/fallback
estão disponíveis e settle/refund é durável.
- `control_plane`: dashboard, UI de cobrança, chaves, créditos, docs, trust e
superfícies de status.
Os watchdogs de deploy e alertas internos de burn-rate usam `router_core` por padrão.
Falhas exclusivas 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 mínimos 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 caso de falhas do provedor upstream. `trustedrouter/eu` prefere o pool de provedores focado na UE, `trustedrouter/zdr` força um piso de provedores de retenção zero com a Anthropic primeiro, e `trustedrouter/e2e` força rotas confidenciais + E2EE com a Tinfoil primeiro. Requisições de chat também respeitam os filtros de roteamento `models` e `provider` no estilo OpenRouter (`order`, `only`, `ignore`, `allow_fallbacks`, `min_privacy`, `data_collection`, `sort`, `max_price`, `require_parameters` e `zdr`), para que os clientes possam solicitar cadeias de fallback explícitas ou preferências de provedor. `provider.order` é uma preferência enquanto os fallbacks estão habilitados, e provedores não listados permanecem elegíveis após a lista preferencial. Com `allow_fallbacks=false`, o roteamento é restrito ao conjunto ordenado de provedores e apenas sua primeira rota disponível é autorizada. `provider.only` é sempre uma allowlist rígida de provedores. Definir `allow_fallbacks=false` no nível superior da requisição ou como `provider.allow_fallbacks` também impede a substituição por outro modelo. `min_privacy="confidential"` é um requisito rígido de confidential-compute + E2EE do 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 recorrer a uma rota mais fraca. Opções de requisição ou de provedor desconhecidas retornam `400` com o nome exato do campo. Controles OpenRouter reconhecidos que não estão implementados retornam um `501 not_supported_in_alpha` estável; eles nunca são aceitos como no-ops do roteador.
- Cobrança: créditos pré-pagos e BYOK primeiro; nenhuma assinatura é necessária.
- Confiança: open source hospedado, com o commit de origem da API em execução, referência de imagem, digest de imagem e política de atestação publicados em `trust.trustedrouter.com`.
- Cadastro: o cadastro por e-mail cria uma chave de gerenciamento de uso único para o workspace.
- Carteira/cripto: o checkout com stablecoin é conectado por meio do método de pagamento Crypto do Stripe Checkout quando solicitado. O Checkout por cartão/padrão permanece o caminho padrão.
## Meta de Escala
O objetivo é suportar escala de 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 ativamente roteáveis.
- 60+ provedores.
- Sobrecarga de roteamento global competitiva com roteadores implantados na borda.
A implantação de produção atual **ainda não** atinge essa meta. Ela executa o plano de controle em quatro regiões do GCP atrás de um LB global com Serverless NEGs por região e quatro regiões de API atestadas ativas. A capacidade escala horizontalmente à medida que mais pools atestados entram em operação; correção, confiança, cobrança e compatibilidade com SDK 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 apenas se o caminho crítico evitar gargalos globais por requisição. Isso significa frotas de gateways sem estado regionais, pools de provedores regionais, leases de cota fragmentados, gravações de metadados somente de acréscimo e agregação assíncrona.
## Latência Atual
Medida desta máquina de desenvolvimento até a API atestada centralizada do GCP `us-central1` em 2 de maio de 2026:
| Sonda | p50 | p95 | Notas |
| --- | ---: | ---: | --- |
| Rejeição de `/v1/chat/completions` não autenticado | 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 concluído | 112 ms | 124 ms | Certificado ACME público termina dentro do enclave. |
| `/attestation` | 1,06 s | 1,12 s | Inclui geração de token de atestação do GCP, portanto não é representativo da sobrecarga normal de roteamento. |
A sobrecarga de rede centralizada é muito maior do que a sobrecarga de borda
reportada pelo OpenRouter, mas a latência do modelo geralmente domina as
requisições interativas. O primeiro passo de escalonamento em produção deve ser
multi-região, em vez de construir uma borda global personalizada imediatamente.
## Forma de Escalonamento Horizontal
O caminho de produção foi projetado para escalar mantendo o gateway de prompts
sem estado:
- As instâncias de `api.trustedrouter.com` podem ser replicadas por trás de
passthrough TCP. Elas autorizam, reservam e liquidam através do control
plane, mas os bytes do prompt nunca saem do caminho atestado.
- O Spanner armazena estado de control-plane e de cobrança com consistência
forte: usuários, workspaces, chaves, metadados de BYOK, idempotência de
eventos de pagamento, saldos, agregados, reservas ativas e uma janela de
auditoria de requisições terminais de 30 dias.
- O Bigtable armazena metadados de atividade de alto volume e limitados,
indexados por workspace e data. Benchmarks de atividade e de provedores
retêm 30 dias, amostras sintéticas brutas retêm 14 dias e rollups compactos
de status retêm 24 meses. Prompt, saída e argumentos de chamadas de
ferramentas não são armazenados.
- A verificação de chave de API usa um hash de lookup de alta entropia para
leituras pontuais; ela não varre chaves.
- Os limites de taxa são aplicados antes dos route handlers e usam o
armazenamento configurado, de modo que os contadores de produção são
compartilhados entre as instâncias do Cloud Run.
Em tráfego na escala do OpenRouter, o próximo gargalo não é o binário do
enclave; é o caminho síncrono de cobrança/autorização. A arquitetura precisa de
reservas fragmentadas, clusters regionais do Bigtable, limites de borda do
Cloud Armor e múltiplas réplicas de gateway antes que o tráfego público possa
ser liberado para crescer.
## Plano Multi-Região
Multi-região é viável preservando o limite de confiança, mas precisa ser feito
com cuidado:
São Paulo (`southamerica-east1`) continua sendo um control plane ativo do
Cloud Run: o `trusted-router` continua implantando e servindo através do load
balancer global. Apenas seu MIG de gateway de enclave foi desativado
(quill-cloud-proxy #309); seu registro DNS regional de gateway obsoleto foi
excluído. As regiões de implantação do control-plane permanecem `us-central1`,
`us-east4`, `europe-west4` e `southamerica-east1`.
Oregon (`us-west1`) é o caso oposto: uma região somente de gateway. Ela executa
um pool de gateways atestados em `api-us-west1.quillrouter.com` e não possui
control plane do Cloud Run. Seu gateway alcança o control plane através do load
balancer global, que o encaminha para a região de control-plane mais próxima
(`us-central1`). Nada em `scripts/deploy` cria um serviço do Cloud Run, job do
scheduler ou NEG ali, e ela não tem entrada nos padrões de warm-region ou
min-instances.
- Execute pools de gateway atestados e aquecidos independentes em `us-central1`, `us-east4`, `europe-west4` e `us-west1`. O inventário de enclaves é `src/trusted_router/enclave_regions.py`, compartilhado por sondas sintéticas, verificações de fumaça de provedores, os padrões do watchdog e os padrões de implantação de `TR_REGIONS`. O mesmo módulo nomeia as regiões de gateway que não possuem plano de controle local (`ENCLAVE_REGIONS_WITHOUT_LOCAL_CONTROL_PLANE`).
- Mantenha as chaves privadas TLS dentro de cada carga de trabalho regional do Confidential Space.
- Mantenha a emissão de certificados dentro da carga de trabalho atestada. Os certificados são compartilhados entre réplicas por meio do cache criptografado. Um primeiro nome de host regional é exposto a apenas um nó depois que todos os nós passam pela atestação canônica e por um PONG estabilizado; ele é expandido apenas depois que o certificado regional e os mesmos critérios passam em todos os nós.
- Mantenha nomes de host regionais como `api-us-central1.quillrouter.com`, `api-us-east4.quillrouter.com`, `api-europe-west4.quillrouter.com` e `api-us-west1.quillrouter.com` para atestação determinística, testes de fumaça e failover do SDK.
- Coloque `api.trustedrouter.com` atrás de DNS por latência/geo ou passthrough TCP que não encerre o TLS. O proxy orange-cloud da Cloudflare permanece incompatível com a alegação de confiança do caminho de prompt.
- Autorize por meio de linhas de cobrança fragmentadas, não por uma única mutação de contador global do Spanner para cada requisição. Novos workspaces e chaves começam com 16 fragmentos de cobrança exatos. As concessões de cota regionais permanecem trabalho futuro: os pilotos de cota regional e concessão de gastos de 2026-09 foram removidos.
- Grave metadados de geração em clusters regionais do Bigtable e, em seguida, agregue em visões globais de atividade de forma assíncrona.
- Mantenha o roteamento de provedores regional, com circuit breakers específicos por provedor, política de fallback e limites de taxa por provedor.
A regra de design fundamental: uma indisponibilidade regional pode falhar de forma fechada ou rotear para outra região atestada, mas nunca deve degradar silenciosamente para um manipulador 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 uma meta até que existam pelo menos 30-60 dias de tempo de atividade medido de 99,99% do router-core.
Disponibilidade do router-core significa:
- o TLS atestado está acessível;
- a validação de chave de API e a autorização do gateway funcionam;
- candidatos de rota são retornados e o fallback pode escolher um provedor saudável;
- a liquidação/reembolso é durável ou seguramente reparável;
- nenhuma requisição de prompt jamais recorre a um caminho não atestado.
Os caminhos de código que suportam este roteiro hoje são:
- `/status.json` exporta `slo_classes.router_core`, `slo_classes.control_plane` e alertas de taxa de consumo para janelas de 5m, 1h, 6h e 24h.
- O watchdog de implantação lê `router_core` por padrão, de modo que indisponibilidades apenas de provedores não revertem automaticamente uma implantação do plano de controle.
- Espera-se que os SDKs tentem novamente falhas de conexão e 502/503/504 em endpoints atestados regionais antes de expor a falha.
- As gravações de atividade no Bigtable são reparáveis a partir da caixa de saída de liquidação durável. A liquidação usa IDs de geração determinísticos, de modo que as novas tentativas sobrescrevem as mesmas linhas de índice e não podem cobrar em dobro nem duplicar a atividade.
Antes de descrever quatro noves como disponibilidade medida em vez de meta, exija três regiões atestadas do GCP aquecidas, paginação testada, testes de caos do router-core, implantações regionais escalonadas com critérios de reversão e pelo menos 30 dias de tempo de atividade medido do router-core igual ou superior a 99,99%.
## Contrato Interno do Gateway
O plano de API atestado pode reservar e liquidar o uso sem enviar conteúdo de prompt ou de 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 provider/BYOK, candidatos
de 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 anexa
linhas de atividade apenas com metadados.
- `POST /v1/internal/gateway/refund`: libera reservas após falhas do provider
ou desconexões do cliente.
Defina `TR_INTERNAL_GATEWAY_TOKEN` fora do ambiente de desenvolvimento local.
## Armazenamento em Produção
A produção usa:
```text
TR_STORAGE_BACKEND=spanner-clickhouse
TR_SPANNER_INSTANCE_ID=trusted-router-nam6
TR_SPANNER_DATABASE_ID=trusted-router
TR_OPERATIONAL_ANALYTICS_CLICKHOUSE_URL=http://<clickhouse-ilb>:8123
TR_OPERATIONAL_ANALYTICS_CLICKHOUSE_PASSWORD=<control-read secret>
```
`scripts/deploy-gcp.sh` habilita as APIs, cria a tabela Spanner
`tr_entities`, implanta o Cloud Run e
conecta os metadados de confiança atuais do GCP à página de confiança.
## Faturamento
`POST /v1/billing/checkout` cria uma sessão do Stripe Checkout quando
`TR_STRIPE_SECRET_KEY` está configurado e, caso contrário, retorna uma resposta
mock local determinística. Os webhooks do Stripe creditam os workspaces de forma idempotente usando o
ID do workspace nos metadados do Checkout. Pagamentos com cartão são liquidados imediatamente. Pagamentos
ACH usam `{"payment_method":"ach"}` e só são creditados depois que o Stripe envia
`checkout.session.async_payment_succeeded`; a conclusão do Checkout enquanto o débito
está em processamento nunca concede créditos. `POST /v1/billing/portal` segue o mesmo
padrão Stripe-ou-mock para gerenciamento de faturamento.
Para checkout com stablecoin, envie `{"payment_method":"stablecoin"}`. Quando
`TR_STABLECOIN_CHECKOUT_ENABLED=true`, a sessão do Checkout é criada com
o método de pagamento `crypto` do Stripe e ainda credita o workspace a partir do webhook
`checkout.session.completed` assinado.
ACH usa o método de pagamento `us_bank_account` do Stripe Checkout. O cronograma
de processamento padrão é de 0,8% com limite de $5 e pode ser substituído com
`TR_STRIPE_ACH_FEE_BASIS_POINTS`, `TR_STRIPE_ACH_FEE_FIXED_CENTS` e
`TR_STRIPE_ACH_FEE_MAX_CENTS`. A recarga automática de cartão salvo permanece exclusiva para cartão.