lore-hex/quill-routerRepo TrustedRouter.com per proxy sicuro di LLM
# 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)
# LLM con crittografia end-to-end. Una sola API. Privacy con prova.
Smetti di preoccuparti di chi può vedere i tuoi prompt. Dì al tuo agente di coding di migrare
il tuo progetto, scegli quanto vuoi essere privato, scegli un modello, inserisci una
chiave — fatto. Stessa API, oltre 30 modelli, una sola chiave. Il gateway gira in enclave
hardware e puoi verificare crittograficamente che non registri mai i tuoi dati.
### Migra il tuo progetto con un solo prompt
Incolla questo in Codex, Claude Code o Cursor — fa la migrazione per te:
```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.
```
Poi:
1. **Scegli il tuo livello di privacy o la tua regione** — usa
`{"provider": {"min_privacy": "zdr"}}` per un limite minimo rigido di zero-retention, oppure
`{"provider": {"min_privacy": "confidential"}}` per il limite più rigoroso di
confidential-compute + E2EE. I comodi alias `trustedrouter/zdr` e
`trustedrouter/e2e` (`trustedrouter/confidential`) selezionano quei
pool. Usa `trustedrouter/eu` con
`https://api-europe-west4.quillrouter.com/v1` per un routing orientato all'UE.
2. **Scegli un modello** — uno qualsiasi tra centinaia, oppure `trustedrouter/auto` per un fallback
automatico quando l'ampiezza dei provider conta più del filtro
di privacy più rigoroso.
3. **Registrati, aggiungi una carta, ottieni la tua chiave** su https://trustedrouter.com.
4. **Distribuisci** — i tuoi prompt ora passano attraverso un percorso che puoi verificare.
<details>
<summary>Preferisci configurarlo 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>
- **Ottieni una chiave / sostienimi:** https://trustedrouter.com
- **Provalo prima (senza registrazione):** https://trustedrouter.com/chat
- **I dettagli tecnici (per gli appassionati):** https://trustedrouter.com/security
- **Genera immagini:** [docs/image-generation.md](https://github.com/lore-hex/quill-router/blob/main/docs/image-generation.md)
- **Genera video:** [docs/video-generation.md](https://github.com/lore-hex/quill-router/blob/main/docs/video-generation.md)
- **Perché l'abbiamo creato:** https://jperla.com/blog/attestation-is-all-you-need
---
<details>
<summary><strong>Per gli appassionati: come la privacy è dimostrabile</strong></summary>
Il gateway di TrustedRouter viene eseguito all'interno di GCP Confidential Space. La piattaforma firma
una misurazione del container in esecuzione. Verifica tale evidenza firmata e confronta
il suo digest dell'immagine con la misurazione della release pubblicata. La revisione del codice sorgente e la
provenienza della build di rilascio stabiliscono cosa fa quell'immagine misurata; un digest
corrispondente da solo non dimostra l'assenza di bug o di logging.
Ispeziona l'evidenza GCP, senza account:
```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.
```
Salvare o decodificare un JWT **non è verifica**. Usa il
[verificatore di attestazione](https://github.com/Lore-Hex/quill-cloud-proxy/blob/main/tools/verify-attestation.py)
da un checkout revisionato di `quill-cloud-proxy` per verificare issuer/firma,
nonce fresco, binding del certificato TLS/exporter e la misurazione di rilascio attesa.
Per un endpoint GCP, esegui da quel 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"
```
Il verificatore recupera prove fresche sulla connessione TLS che verifica. Quel
controllo non attesta una successiva, separata connessione `curl` o SDK. Questi esempi
usano il nome host GCP US Central pubblicato per selezionare il formato delle prove GCP. L'endpoint
globale può selezionare un altro cloud; usa la sua politica di verifica specifica per il cloud
e le misurazioni da [il sito di fiducia](https://trust.trustedrouter.com/).
| | modello di fiducia |
|---|---|
| OpenRouter, provider ospitati | "Non registriamo log." Una politica che non puoi verificare. |
| Portkey, Cloudflare AI Gateway | Registra tutto per l'osservabilità. |
| LiteLLM | Self-host, ma il proxy in esecuzione non è verificato. |
| **TrustedRouter** | **Open source + attestazione hardware. Verifica il percorso del codice; non registra nulla.** |
Ambito onesto: l'attestazione dimostra che il binario in esecuzione è il binario pubblicato su
hardware che puoi sfidare con un nonce. Non sconfigge uno stato-nazione con
accesso fisico all'host, e non dimostra che il binario open-source sia privo di bug.
L'ancora di fiducia è la catena di attestazione supportata dall'hardware di Google Confidential Computing.
I provider upstream gestiscono i prompt secondo
le proprie politiche — la postura di ciascun provider è pubblicata nelle pagine dei modelli.
</details>
---
## Struttura del repository
Questo repo implementa il contratto del control-plane: copertura delle route, gestione di auth/key,
semantica del registro di fatturazione, metadati di utilizzo, divieti di logging di prompt/output,
scrubber Sentry e astrazioni dei provider. L'implementazione del gateway attestato
si trova in `quill-cloud-proxy`.
Confine di fiducia: `api.trustedrouter.com` è il percorso attestato dei prompt e deve
terminare TLS all'interno di Confidential Space. `trustedrouter.com` è il control
plane e non deve mai servire un fallback di inferenza di produzione.
`api.quillrouter.com` rimane un alias permanente funzionante (stesso gateway attestato
e certificato), così le integrazioni esistenti continuano a funzionare senza migrazione.
## Locale
```bash
uv sync
uv run pytest
uv run uvicorn trusted_router.main:app --reload
```
Smoke test end-to-end su un'istanza in esecuzione:
```bash
TR_SMOKE_BASE_URL=http://127.0.0.1:18080/v1 uv run python scripts/smoke_e2e.py
```
Per la produzione, impostare `TR_SMOKE_BASE_URL=https://api.trustedrouter.com/v1` e
`TR_SMOKE_INTERNAL_TOKEN` se le route del gateway interno sono protette da token.
Impostare le chiavi locali di operator/provider in:
```text
/Users/jperla/claude/.quill_cloud_keys.private
```
Quel file non viene mai committato. Si prevede che sia in stile 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=...
```
Lo script di deploy accetta anche alias locali già usati in alcuni file degli operatori: `CLAUDE_API_KEY` per Anthropic, `CHATGPT_API_KEY` per OpenAI e `STRIPE_KEY` per `STRIPE_SECRET_KEY`.
Vertex è diverso dalle altre piattaforme provider: i deploy GCP di produzione usano il service account di Cloud Run o Confidential Space e token di accesso Google di breve durata da metadata/ADC. Non inserire una chiave Vertex di lunga durata in questo file per la route Vertex prepagata first-party; concedi invece le autorizzazioni Vertex al service account di runtime.
## Licenza
Business Source License 1.1. Il codice sorgente è pubblico così che chiunque possa leggere, compilare e verificare il codice esatto alla base delle dichiarazioni sulla privacy e sull'attestazione di TrustedRouter (https://trust.trustedrouter.com) — è a questo che serve. L'uso non di produzione (revisione di sicurezza, audit, valutazione locale) è gratuito. L'uso in produzione richiede una licenza commerciale da Lore Hex Corp: [email protected]. Ogni versione passa alla Apache License 2.0 quattro anni dopo la pubblicazione. Il codice pubblicato prima del 3 luglio 2026 rimane Apache-2.0.
## Sicurezza predefinita
- Il contenuto dei prompt e degli output non viene mai registrato nei log. L'inferenza sincrona e in streaming ordinaria non lo conserva. La Batch API opt-in conserva temporaneamente artefatti cifrati dall'enclave per un massimo di 30 giorni.
- I log di utilizzo contengono solo metadati.
- Le chiavi API sono memorizzate come hash SHA-256 con salt con ID chiave opachi.
- Le chiavi dei provider BYOK inviate dagli utenti sono memorizzate come righe di testo cifrato con envelope encryption, non come un oggetto Secret Manager per chiave. In produzione, Cloud KMS avvolge la DEK per chiave; i riferimenti esterni `env://...` restano supportati per le chiavi gestite dall'operatore.
- Le autorizzazioni del gateway includono un `byok_cache_key` non segreto per gli envelope BYOK cifrati. I gateway attestati lo usano per una cache in memoria delle chiavi decifrate con TTL breve; la rotazione BYOK cambia la chiave e l'eliminazione interrompe la restituzione dell'envelope.
- Le chiavi BYOK in chiaro sono solo input monouso; le risposte pubbliche/del control-plane espongono solo un breve suggerimento sui primi/ultimi caratteri della chiave e metadati di riferimento cifrati, mai il testo in chiaro.
- La configurazione di produzione fallisce in modo chiuso senza un token interno del gateway, un segreto webhook Stripe firmato e un backend di archiviazione non in memoria.
- Le app del control-plane di produzione non registrano `/chat/completions`, `/messages`, `/responses` o `/embeddings`; questi appartengono al piano API attestato.
- Sentry è solo per il control-plane e oscura i corpi delle richieste, gli header di autenticazione, le chiavi API, le chiavi BYOK, i messaggi dei prompt e il testo degli output. Un flood gate Sentry lato client limita i problemi ripetuti per fingerprint e gli eventi totali per processo/finestra, così una singola integrazione rumorosa non può consumare di nuovo l'intero budget di errori.
- Nessuna configurazione Sentry deve trovarsi nell'enclave attestata.
## Osservabilità Broadcast
I proprietari del workspace possono configurare le destinazioni Broadcast su `/v1/broadcast/destinations` o nella console sotto Broadcast. Le destinazioni supportate sono PostHog e webhook OTLP JSON. Broadcast è solo metadati per impostazione predefinita: modello, provider, conteggi dei token, latenza, costo, tipo di route, regione e metadati di trace personalizzati. Il contenuto dei prompt/output viene esportato solo quando una destinazione abilita esplicitamente `include_content`; tali destinazioni cifrate con contenuto abilitato vengono restituite solo al gateway attestato, non alle normali risposte di gestione. Le consegne solo metadati vengono scritte prima in una outbox Broadcast persistente e svuotate in modo asincrono da `/internal/broadcast/drain`, così un'interruzione di PostHog/webhook non blocca l'inferenza né perde i metadati già regolati al riavvio del processo.
## Livelli di routing fissi
Questi alias usano un pool di modelli esplicitamente ordinato: il primo membro è preferito e gli altri sono fallback. Eseguono un modello per tentativo, senza sintesi, orchestrazione o soglia di privacy implicita. Imposta `provider.min_privacy` esplicitamente quando necessario. Il catalogo live `/v1/models` pubblica ogni pool in `auto_candidates`.
- `trustedrouter/frontier`: pool fisso di modelli frontier.
- `trustedrouter/advanced`: pool fisso di modelli advanced.
- `trustedrouter/professional`: pool fisso di modelli professional.
- `trustedrouter/efficient`: pool fisso di modelli efficient.
## Monitoraggio sintetico
TrustedRouter dispone di un piano di monitoraggio sintetico separato per l'uptime pubblico.
I worker sintetici vengono eseguiti all'esterno dell'enclave, inviano piccole richieste reali
all'API pubblica attestata e memorizzano solo metadati. Gli alias dei modelli di monitoraggio sono:
- `trustedrouter/free`: pool gratuito in stile OpenRouter. Utile per gli utenti, non è un
segnale SLA.
- `trustedrouter/cheap`: pool a pagamento più economico con diversità tra provider.
- `trustedrouter/eu`: pool di provider orientato all'UE. Preferisce provider europei,
collocabili nell'UE e attenti alla privacy, soprattutto se abbinato a
`https://api-europe-west4.quillrouter.com/v1`. Si tratta di una politica di routing, non
di una garanzia generale di residenza dei dati.
- `trustedrouter/monitor`: pool interno per l'uptime usato per i controlli PONG e di fallback.
È visibile nel catalogo per trasparenza, ma l'autorizzazione richiede la
`TR_SYNTHETIC_MONITOR_API_KEY` configurata; le normali chiavi API ricevono 403.
I worker devono essere eseguiti da `us-central1` e `europe-west4`, utilizzando un workspace/chiave
dedicato `trustedrouter-synthetic-monitoring` con limiti di spesa rigidi e
ricarica automatica. I campioni grezzi sono righe Bigtable append-only; le pagine di stato pubbliche
leggono rollup compatti esposti su `/status`, `/status.json` e
`/status/history?window=5m|24h|daily`. Le generazioni sintetiche usano
l'etichetta applicativa `TrustedRouter Synthetic` e sono escluse dalle analisi
di clienti/app.
Ogni invocazione del monitor esegue anche un completamento chat con `stream: true` e fallisce
se non riceve un evento dati SSE, un chunk terminale e `[DONE]`. Il
job ricorrente Stage D aggiunge `--expect-stage-d`, quindi cerca l'autorizzazione tipizzata di quella richiesta
e richiede un `stage_d_boot_kid` associato più
`heartbeat_seq > 0`. Il suo workspace è intenzionalmente separato: provisionarlo
con `scripts/provision_stage_d_probe_workspace.py` e aggiungere il suo id a
`TR_STAGE_D_PILOT_WORKSPACE_IDS`. La chiave deve essere una
chiave locale tipizzata abilitata all'heartbeat; il deploy la legge da
`trustedrouter-stage-d-probe-api-key` e usa `trustedrouter/cheap` in modo che sia
indipendente dalla normale chiave solo-monitor. Il rollout normale lascia disabilitata l'idoneità
allo Stage D, quindi creare la chiave da sola non abilita lo Stage D.
La misurazione dei provider utilizza due classi di probe indipendenti:
- Le sonde PONG brevi coprono casualmente l'intero catalogo attivo e misurano uptime,
TTFB, TTFT e drift dell'API upstream.
- Uno stream sostenuto di 512 token copre le 200 rotte provider/modello più importanti
in rotazione deterministica da `us-central1`. Misura i token di output
al secondo dopo il primo token. Viene eseguito in un Cloud Run Job separato,
così gli stream lenti non possono ritardare le sonde di uptime. I fallimenti delle sonde lunghe non contano
mai ai fini degli avvisi di uptime del provider o di drift dell'API.
L'attuale pianificazione di due minuti fornisce a ciascuna rotta sostenuta circa 25 campioni a
settimana e 108 ogni 30 giorni. La CI calcola una stima di spesa a capacità massima dal catalogo
live e fallisce se supera il tetto mensile revisionato.
Lo stato separa due classi di SLO del servizio invece di mescolarle con
il comportamento dei provider upstream:
- `router_core`: API attestata raggiungibile, autorizzazione della chiave funzionante, candidati di rotta/fallback
disponibili e settle/refund durevole.
- `control_plane`: dashboard, UI di fatturazione, chiavi, crediti, documentazione, trust e
superfici di stato.
I watchdog di deploy e gli avvisi interni di burn-rate usano per impostazione predefinita `router_core`.
I fallimenti relativi solo ai provider sono misurati per provider su `/status` e
`/leaderboard`; non consumano il budget di errore di router-core quando il fallback
rimane disponibile.
## Posizionamento pubblico
- Prezzi: l'utilizzo prepagato e BYOK è tracciato come microdollari interi, non
dollari in virgola mobile, così i costi minimi dei token restano verificabili nel registro.
- Obiettivo di uptime: `trustedrouter/auto` è un vero alias di modello chat nell'inferenza
del control-plane locale/di test e passa al provider configurato successivo in caso di
errori del provider upstream. `trustedrouter/eu` preferisce il pool di provider orientato
all'UE, `trustedrouter/zdr` impone un livello minimo di provider a ritenzione zero con
Anthropic per primo, e `trustedrouter/e2e` impone route confidenziali + E2EE con
Tinfoil per primo. Le richieste chat rispettano anche i filtri di routing in stile
OpenRouter `models` e `provider` (`order`, `only`, `ignore`, `allow_fallbacks`,
`min_privacy`, `data_collection`, `sort`, `max_price`, `require_parameters`,
e `zdr`) così i client possono richiedere catene di fallback esplicite o preferenze
di provider. `provider.order` è una preferenza finché i fallback sono abilitati, e i
provider non elencati restano idonei dopo la lista preferita. Con
`allow_fallbacks=false`, il routing è limitato all'insieme ordinato di provider e solo
la sua prima route disponibile è autorizzata. `provider.only` è sempre una allowlist
rigida di provider. Impostare `allow_fallbacks=false` al livello superiore della
richiesta o come `provider.allow_fallbacks` impedisce anche la sostituzione con un
altro modello. `min_privacy="confidential"` è un requisito rigido lato provider di
confidential-compute + E2EE e fallisce in modo chiuso; gli alias del valore della
richiesta `e2e` e `e2ee` selezionano lo stesso livello invece di ricadere su una route
più debole. Opzioni di richiesta o provider sconosciute restituiscono `400` con il nome
esatto del campo. I controlli OpenRouter riconosciuti ma non implementati restituiscono
un `501 not_supported_in_alpha` stabile; non vengono mai accettati come no-op del
router.
- Fatturazione: crediti prepagati e BYOK per primi; non è richiesto alcun abbonamento.
- Fiducia: open source ospitato, con il commit sorgente dell'API in esecuzione, il
riferimento dell'immagine, il digest dell'immagine e la policy di attestazione
pubblicati su `trust.trustedrouter.com`.
- Registrazione: la registrazione via email crea una chiave di gestione monouso per il
workspace.
- Wallet/crypto: il checkout in stablecoin è collegato tramite il metodo di pagamento
Crypto di Stripe Checkout quando richiesto. Il Checkout con carta/predefinito resta il
percorso predefinito.
## Obiettivo di scala
L'obiettivo è supportare una scala di livello OpenRouter:
- 1 trilione di token/giorno, ovvero circa 11,6 milioni di token/secondo in media su un
giorno.
- 1-4 milioni di account sviluppatore.
- Oltre 300 modelli attivamente instradabili.
- Oltre 60 provider.
- Overhead di routing globale competitivo con router distribuiti all'edge.
Il deployment di produzione attuale **non** raggiunge ancora tale obiettivo. Esegue
il control plane in quattro regioni GCP dietro un LB globale con Serverless NEG per
regione e quattro regioni API attestate attive. La capacità scala
orizzontalmente man mano che vengono attivati più pool attestati; correttezza, fiducia,
fatturazione e compatibilità SDK sono in regime stazionario.
Il volume delle richieste dipende fortemente dalla dimensione media della generazione. A
1 trilione di token/giorno:
| Token medi/richiesta | Richieste/giorno | Tasso medio di richieste |
| ---: | ---: | ---: |
| 1.000 | 1,0B | 11,6k rps |
| 2.500 | 400M | 4,6k rps |
| 10.000 | 100M | 1,2k rps |
L'architettura può evolvere a questa scala, ma solo se il percorso critico evita
colli di bottiglia globali per richiesta. Ciò significa flotte di gateway stateless
regionali, pool di provider regionali, lease di quota shardizzati, scritture di metadati
append-only e aggregazione asincrona.
## Latenza attuale
Misurata da questa macchina di sviluppo verso l'API attestata centralizzata GCP
`us-central1` il 2 maggio 2026:
| Sonda | p50 | p95 | Note |
| --- | ---: | ---: | --- |
| Rifiuto di `/v1/chat/completions` non autenticato | 174 ms | 184 ms | Include DNS, TCP, TLS pubblico, gestione della richiesta nell'enclave. |
| Connessione TCP | 55 ms | 59 ms | Percorso di rete verso `us-central1` da questa macchina. |
| Handshake TLS completato | 112 ms | 124 ms | Il certificato ACME pubblico termina all'interno dell'enclave. |
| `/attestation` | 1,06 s | 1,12 s | Include la generazione del token di attestazione GCP, quindi non è rappresentativo dell'overhead di routing normale. |
L'overhead di rete centralizzato è molto più alto dell'overhead edge
riportato da OpenRouter, ma la latenza del modello di solito domina le richieste
interattive. Il primo passo di scalabilità in produzione dovrebbe essere
multi-regione anziché costruire immediatamente un edge globale personalizzato.
## Forma della scalabilità orizzontale
Il percorso di produzione è progettato per scalare mantenendo il gateway dei
prompt stateless:
- Le istanze di `api.trustedrouter.com` possono essere replicate dietro un
passthrough TCP. Autorizzano, prenotano e regolano tramite il control plane,
ma i byte del prompt non lasciano mai il percorso attestato.
- Spanner memorizza lo stato del control plane e della fatturazione con
consistenza forte: utenti, workspace, chiavi, metadati BYOK, idempotenza degli
eventi di pagamento, saldi, aggregati, prenotazioni attive e una finestra di
audit delle richieste terminali di 30 giorni.
- Bigtable memorizza metadati di attività ad alto volume e limitati, indicizzati
per workspace e data. Le attività e i benchmark dei provider conservano 30
giorni, i campioni sintetici grezzi conservano 14 giorni e i rollup compatti
di stato conservano 24 mesi. Prompt, output e argomenti delle tool-call non
vengono memorizzati.
- La verifica delle chiavi API utilizza un hash di lookup ad alta entropia per
le letture puntuali; non esegue scansioni delle chiavi.
- I rate limit vengono applicati prima degli handler di routing e utilizzano
l'archivio configurato, così i contatori di produzione sono condivisi tra le
istanze Cloud Run.
Con un traffico su scala OpenRouter, il prossimo collo di bottiglia non è il
binario dell'enclave; è il percorso sincrono di fatturazione/autorizzazione.
L'architettura necessita di prenotazioni shardizzate, cluster Bigtable
regionali, limiti edge Cloud Armor e più repliche del gateway prima che il
traffico pubblico possa essere incrementato.
## Piano multi-regione
Il multi-regione è fattibile preservando il confine di fiducia, ma deve essere
realizzato con attenzione:
San Paolo (`southamerica-east1`) rimane un control plane Cloud Run attivo:
`trusted-router` continua a essere distribuito e a servire tramite il load
balancer globale. Solo il suo MIG del gateway enclave è stato dismesso
(quill-cloud-proxy #309); il suo record DNS regionale obsoleto del gateway è
stato eliminato. Le regioni di deployment del control plane rimangono
`us-central1`, `us-east4`, `europe-west4` e `southamerica-east1`.
L'Oregon (`us-west1`) è il caso opposto: una regione solo gateway. Esegue un
pool di gateway attestati su `api-us-west1.quillrouter.com` e non ha alcun
control plane Cloud Run. Il suo gateway raggiunge il control plane tramite il
load balancer globale, che lo indirizza alla regione del control plane più
vicina (`us-central1`). Nulla in `scripts/deploy` crea un servizio Cloud Run, un
job scheduler o un NEG in quella regione, e non ha alcuna voce nei default delle
regioni warm o delle min-instances.
- Eseguire pool di gateway attestati warm indipendenti in `us-central1`, `us-east4`,
`europe-west4` e `us-west1`. L'inventario degli enclave è
`src/trusted_router/enclave_regions.py`, condiviso da sonde sintetiche, controlli
smoke dei provider, i default del watchdog e i default di deploy `TR_REGIONS`. Lo
stesso modulo elenca le regioni gateway che non hanno un control plane locale
(`ENCLAVE_REGIONS_WITHOUT_LOCAL_CONTROL_PLANE`).
- Mantenere le chiavi private TLS all'interno di ciascun workload regionale Confidential Space.
- Mantenere l'emissione dei certificati all'interno del workload attestato. I certificati sono
condivisi tra le repliche tramite la cache cifrata. Un hostname regionale iniziale viene
esposto a un solo nodo solo dopo che ogni nodo supera l'attestazione canonica
e un PONG stabilizzato; viene espanso solo dopo che il certificato regionale e gli stessi
gate passano su ogni nodo.
- Mantenere hostname regionali come `api-us-central1.quillrouter.com`,
`api-us-east4.quillrouter.com`, `api-europe-west4.quillrouter.com` e
`api-us-west1.quillrouter.com` per attestazione deterministica,
smoke test e failover degli SDK.
- Mettere `api.trustedrouter.com` dietro DNS basato su latenza/geo o TCP passthrough che non
termini il TLS. Il proxying orange-cloud di Cloudflare resta incompatibile
con la garanzia di fiducia del percorso dei prompt.
- Autorizzare tramite righe di billing shardizzate, non tramite una singola mutazione
di un contatore globale Spanner per ogni richiesta. I nuovi workspace e le nuove chiavi partono con 16
shard di billing esatti. I lease di quota regionali restano lavoro futuro: i piloti
regional-quota e spend-lease di 2026-09 sono stati rimossi.
- Scrivere i metadati di generazione su cluster Bigtable regionali, poi aggregare in
viste di attività globali in modo asincrono.
- Mantenere il routing dei provider regionale, con circuit breaker specifici per provider,
policy di fallback e rate limit per provider.
La regola di progettazione chiave: un'interruzione regionale può fallire in modo chiuso o instradare verso un'altra
regione attestata, ma non deve mai degradare silenziosamente verso un
gestore di prompt non attestato.
## Obiettivo Four-Nines di Router-Core
L'obiettivo è un SLO interno, non un SLA contrattuale. Il 99,99% consente circa
52 minuti e 36 secondi di downtime all'anno. Lo stato pubblico etichetta questo numero
come obiettivo finché non esistono almeno 30-60 giorni di uptime misurato del router-core
pari al 99,99%.
La disponibilità del router-core significa:
- il TLS attestato è raggiungibile;
- la validazione della chiave API e l'autorizzazione del gateway funzionano;
- vengono restituiti candidati di route e il fallback può scegliere un provider sano;
- il settlement/refund è durevole o riparabile in sicurezza;
- nessuna richiesta di prompt ricade mai su un percorso non attestato.
I percorsi di codice che supportano oggi questa roadmap sono:
- `/status.json` esporta `slo_classes.router_core`,
`slo_classes.control_plane` e avvisi di burn-rate per finestre di 5m, 1h, 6h e 24h.
- Il watchdog di deploy legge `router_core` per impostazione predefinita, quindi le interruzioni dei soli provider
non annullano automaticamente un deploy del control-plane.
- Gli SDK devono ritentare i fallimenti di connessione e i 502/503/504 attraverso
endpoint attestati regionali prima di segnalare il fallimento.
- Le scritture di attività su Bigtable sono riparabili dalla outbox di settlement durevole.
Il settlement usa ID di generazione deterministici, quindi i retry sovrascrivono le stesse
righe di indice e non possono addebitare due volte o duplicare l'attività.
Prima di descrivere i four nines come disponibilità misurata anziché come obiettivo,
sono necessarie tre regioni GCP attestate warm, paging testato, test chaos
del router-core, deploy regionali a fasi con gate di rollback e almeno 30 giorni di
uptime misurato del router-core pari o superiore al 99,99%.
## Contratto interno del Gateway
Il piano API attestato può riservare e regolare l'utilizzo senza inviare il contenuto dei prompt o
dell'output al control plane:
- `POST /v1/internal/gateway/authorize`: convalida l'hash della chiave API, riserva
crediti/limiti della chiave e restituisce i metadati di routing provider/BYOK, i
candidati di route derivati dai filtri di richiesta `model`, `models` e `provider`,
e gli endpoint regionali configurati.
- `POST /v1/internal/gateway/settle`: regola l'utilizzo riuscito e aggiunge
righe di attività contenenti solo metadati.
- `POST /v1/internal/gateway/refund`: rilascia le prenotazioni dopo errori del
provider o disconnessioni del client.
Impostare `TR_INTERNAL_GATEWAY_TOKEN` al di fuori dello sviluppo locale.
## Archiviazione in produzione
La produzione utilizza:
```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` abilita le API, crea la tabella Spanner
`tr_entities`, esegue il deploy su Cloud Run e
collega i metadati di trust GCP correnti alla pagina di trust.
## Fatturazione
`POST /v1/billing/checkout` crea una sessione Stripe Checkout quando
`TR_STRIPE_SECRET_KEY` è configurata e, in caso contrario, restituisce una risposta
mock locale deterministica. I webhook Stripe accreditano i workspace in modo idempotente utilizzando
l'ID del workspace nei metadati di Checkout. I pagamenti con carta vengono regolati immediatamente. I pagamenti
ACH utilizzano `{"payment_method":"ach"}` e vengono accreditati solo dopo che Stripe invia
`checkout.session.async_payment_succeeded`; il completamento di Checkout mentre l'addebito
è in elaborazione non concede mai crediti. `POST /v1/billing/portal` segue lo stesso
schema Stripe-o-mock per la gestione della fatturazione.
Per il checkout stablecoin, inviare `{"payment_method":"stablecoin"}`. Quando
`TR_STABLECOIN_CHECKOUT_ENABLED=true`, la sessione Checkout viene creata con
il metodo di pagamento `crypto` di Stripe e accredita comunque il workspace dal webhook
`checkout.session.completed` firmato.
ACH utilizza il metodo di pagamento `us_bank_account` di Stripe Checkout. La pianificazione
di elaborazione predefinita è dello 0,8% con un massimo di $5 e può essere sovrascritta con
`TR_STRIPE_ACH_FEE_BASIS_POINTS`, `TR_STRIPE_ACH_FEE_FIXED_CENTS` e
`TR_STRIPE_ACH_FEE_MAX_CENTS`. Il ricaricamento automatico con carta salvata rimane solo per carta.