Pour la production, définissez `TR_SMOKE_BASE_URL=https://api.trustedrouter.com/v1` et
`TR_SMOKE_INTERNAL_TOKEN` si les routes de la passerelle interne sont protégées par jeton.

Définissez les clés locales d'opérateur/fournisseur dans :```text
/Users/jperla/claude/.quill_cloud_keys.private

Le script de déploiement accepte également des alias locaux déjà utilisés dans certains fichiers d’opérateur : `CLAUDE_API_KEY` pour Anthropic, `CHATGPT_API_KEY` pour OpenAI, et `STRIPE_KEY` pour `STRIPE_SECRET_KEY`.

Vertex est différent des autres plateformes de fournisseurs : les déploiements GCP de production utilisent le compte de service Cloud Run ou Confidential Space et des jetons d’accès Google à courte durée de vie issus de metadata/ADC. Ne placez pas de clé Vertex à longue durée de vie dans ce fichier pour la route Vertex prépayée propriétaire ; accordez plutôt les permissions Vertex au compte de service d’exécution.

## Licence

Business Source License 1.1. Le code source est public afin que chacun puisse lire, compiler et vérifier le code exact derrière les affirmations de confidentialité et d’attestation de TrustedRouter (https://trust.trustedrouter.com) — c’est précisément à cela qu’il sert. L’utilisation hors production (revue de sécurité, audit, évaluation locale) est gratuite. L’utilisation en production nécessite une licence commerciale de Lore Hex Corp :
[email protected]. Chaque version est convertie sous Apache License 2.0 quatre ans après sa publication. Le code publié avant le 3 juillet 2026 reste sous Apache-2.0.

## Sécurité par défaut

- Le contenu des prompts et des sorties n’est jamais stocké.
- Les journaux d’utilisation ne contiennent que des métadonnées.
- Les clés API sont stockées sous forme de hachages SHA-256 salés avec des identifiants de clé opaques.
- Les clés fournisseur BYOK soumises par l’utilisateur sont stockées sous forme de lignes de texte chiffré enveloppé, et non un objet Secret Manager par clé. En production, Cloud KMS encapsule la DEK par clé ; les références externes `env://...` restent prises en charge pour les clés gérées par les opérateurs.
- Les autorisations de passerelle incluent une `byok_cache_key` non secrète pour les enveloppes BYOK chiffrées. Les passerelles attestées l’utilisent pour un cache de clés déchiffrées en mémoire uniquement avec un TTL court ; la rotation BYOK change la clé et la suppression cesse de renvoyer l’enveloppe.
- Les clés brutes BYOK ne sont saisies qu’une seule fois ; les réponses du plan public/contrôle n’exposent qu’un court indice de première/dernière partie de clé et des métadonnées de référence chiffrées, jamais le texte en clair.
- La configuration de production échoue de manière sécurisée sans jeton de passerelle interne, sans secret de webhook Stripe signé et sans backend de stockage hors mémoire.
- Les applications du plan de contrôle en production n’enregistrent pas `/chat/completions`, `/messages`, `/responses` ni `/embeddings` ; ces routes appartiennent au plan d’API attesté.
- Sentry est réservé au plan de contrôle et nettoie les corps de requête, les en-têtes d’authentification, les clés API, les clés BYOK, les messages de prompt et le texte de sortie. Un garde-fou Sentry côté client limite les problèmes répétés par empreinte et le nombre total d’événements par processus/fenêtre, afin qu’une seule intégration bruyante ne puisse pas consommer à nouveau tout le budget d’erreurs.
- Aucune configuration Sentry n’appartient à l’enclave attestée.

## Observabilité Broadcast

Les propriétaires d’espace de travail peuvent configurer des destinations Broadcast via `/v1/broadcast/destinations` ou dans la console, sous Broadcast. Les destinations prises en charge sont PostHog et les webhooks JSON OTLP. Broadcast ne contient que des métadonnées par défaut : modèle, fournisseur, nombres de jetons, latence, coût, type de route, région et métadonnées de trace personnalisées. Le contenu des prompts/sorties n’est exporté que lorsqu’une destination active explicitement `include_content` ; ces destinations chiffrées activant le contenu ne sont renvoyées qu’à la passerelle attestée, et non aux réponses de gestion normales. Les livraisons de métadonnées uniquement sont d’abord écrites dans une boîte d’envoi Broadcast persistante, puis vidées de manière asynchrone via `/internal/broadcast/drain`, de sorte qu’une panne de PostHog/webhook ne bloque pas l’inférence ni ne perd les métadonnées déjà réglées au redémarrage du processus.

## Surveillance synthétique

TrustedRouter dispose d’un plan de surveillance synthétique distinct pour la disponibilité publique. Les travailleurs synthétiques s’exécutent hors de l’enclave, envoient de minuscules requêtes réelles vers l’API publique attestée et ne stockent que des métadonnées. Les alias de modèles du moniteur sont :

- `trustedrouter/free` : pool gratuit de type OpenRouter. Utile pour les utilisateurs, mais pas un signal de SLA.
- `trustedrouter/cheap` : pool payant le moins cher avec diversité de fournisseurs.
- `trustedrouter/eu` : pool de fournisseurs axé UE. Il privilégie les fournisseurs européens, régionables UE et respectueux de la vie privée, surtout lorsqu’il est associé à `https://api-europe-west4.quillrouter.com/v1`. Il s’agit d’une politique de routage, pas d’une garantie globale de résidence des données.
- `trustedrouter/monitor` : pool de disponibilité interne pour les contrôles PONG et de repli. Il est visible dans le catalogue par souci de transparence, mais l’autorisation nécessite la `TR_SYNTHETIC_MONITOR_API_KEY` configurée ; les clés API normales reçoivent une erreur 403.

Les travailleurs doivent s’exécuter depuis `us-central1` et `europe-west4`, en utilisant un espace de travail/clé dédié `trustedrouter-synthetic-monitoring` avec des plafonds de dépense stricts et un réapprovisionnement automatique. Les échantillons bruts sont des lignes Bigtable en ajout uniquement ; les pages de statut publiques lisent des agrégats compacts exposés via `/status`, `/status.json` et `/status/history?window=5m|24h|daily`. Les générations synthétiques utilisent le libellé d’application `TrustedRouter Synthetic` et sont exclues des analyses client/application.

La mesure des fournisseurs utilise deux classes de sondes indépendantes :

- De courtes sondes PONG couvrent aléatoirement l’intégralité du catalogue actif et mesurent la disponibilité, le TTFB, le TTFT et la dérive de l’API amont.
- Un flux soutenu de 512 jetons couvre les 200 routes fournisseur/modèle les plus importantes en rotation déterministe depuis `us-central1`. Il mesure les jetons de sortie par seconde après le premier jeton. Il s’exécute dans une tâche Cloud Run distincte, de sorte que les flux lents ne peuvent pas retarder les sondes de disponibilité. Les échecs de sondes longues ne comptent jamais contre la disponibilité des fournisseurs ni contre les alertes de dérive d’API.

Le calendrier actuel de deux minutes donne à chaque route soutenue environ 25 échantillons par semaine et 108 par période de 30 jours. Le CI calcule une estimation complète des dépenses de capacité à partir du catalogue en direct et échoue si elle dépasse le plafond mensuel examiné.

Le statut sépare deux classes de SLO de service au lieu de les mélanger avec le comportement des fournisseurs amont :

- `router_core` : l’API attestée est joignable, l’autorisation des clés fonctionne, les candidats de route/repli sont disponibles, et le règlement/remboursement est durable.
- `control_plane` : tableau de bord, interface de facturation, clés, crédits, documentation, trust et surfaces de statut.

Les chiens de garde de déploiement et les alertes internes de taux de combustion sont par défaut sur `router_core`. Les pannes exclusives aux fournisseurs sont mesurées par fournisseur sur `/status` et `/leaderboard` ; elles ne consomment pas le budget d’erreurs du routeur principal lorsque le repli reste disponible.

## Positionnement public

- Tarification : l’utilisation prépayée et BYOK est suivie en microdollars entiers, et non en dollars à virgule flottante, afin que les coûts minuscules de jetons restent auditable dans le grand livre.
- Cible de disponibilité : `trustedrouter/auto` est un véritable alias de modèle de chat dans l’inférence locale/test du plan de contrôle et bascule vers le prochain fournisseur configuré en cas de défaillance du fournisseur amont. `trustedrouter/eu` privilégie le pool de fournisseurs axé UE, `trustedrouter/zdr` impose un plancher de fournisseur à zéro conservation avec Anthropic en premier, et `trustedrouter/e2e` impose des routes confidentielles + E2EE avec Tinfoil en premier. Les requêtes de chat honorent également les filtres de routage de type OpenRouter `models` et `provider` (`order`, `only`, `ignore`, `allow_fallbacks`, `min_privacy`, `data_collection` et `sort`) afin que les clients puissent demander des chaînes de repli explicites ou des préférences de fournisseur. `min_privacy="confidential"` est une exigence stricte côté fournisseur de calcul confidentiel + E2EE et échoue de manière sécurisée ; les alias de valeur de requête `e2e` et `e2ee` sélectionnent le même niveau au lieu de revenir à une route plus faible.
- Facturation : crédits prépayés et BYOK d’abord ; aucun abonnement requis.
- Confiance : open source hébergé, avec le commit source de l’API en cours d’exécution, la référence d’image, le digest d’image et la politique d’attestation publiés sur `trust.trustedrouter.com`.
- Inscription : l’inscription par e-mail crée une clé de gestion à usage unique pour l’espace de travail.
- Portefeuille/crypto : le paiement en stablecoin est branché via la méthode de paiement Crypto de Stripe Checkout lorsqu’elle est demandée. Checkout par carte/défaut reste le chemin par défaut.

## Cible d’échelle

L’objectif est de prendre en charge une échelle de classe OpenRouter :

- 1 billion de jetons/jour, soit environ 11,6 millions de jetons/seconde en moyenne sur une journée.
- 1 à 4 millions de comptes développeurs.
- 300+ modèles routables actifs.
- 60+ fournisseurs.
- Des frais généraux de routage mondiaux compétitifs avec les routeurs déployés en périphérie.

Le déploiement de production actuel n’atteint **pas** encore cette cible. Il exécute le plan de contrôle dans quatre régions GCP derrière un équilibreur de charge mondial avec des NEG Serverless par région, avec trois régions d’API attestées en direct jusqu’au déploiement de pools régionaux attestés supplémentaires. La capacité évolue horizontalement à mesure que d’autres pools attestés arrivent en ligne ; l’exactitude, la confiance, la facturation et la compatibilité SDK sont en régime permanent.

Le volume de requêtes dépend fortement de la taille moyenne des générations. À 1 billion de jetons/jour :

| Jetons moyens/requête | Requêtes/jour | Débit moyen de requêtes |
| ---: | ---: | ---: |
| 1 000 | 1,0 Md | 11,6 k rps |
| 2 500 | 400 M | 4,6 k rps |
| 10 000 | 100 M | 1,2 k rps |

L’architecture peut évoluer jusqu’à cette échelle, mais uniquement si le chemin critique évite les goulets d’étranglement mondiaux par requête. Cela implique des flottes de passerelles régionales sans état, des pools de fournisseurs régionaux, des baux de quota partitionnés, des écritures de métadonnées en ajout uniquement et une agrégation asynchrone.

## Latence actuelle

Mesurée depuis cette machine de développement vers l’API attestée centralisée GCP `us-central1` le 2 mai 2026 :

| Sonde | p50 | p95 | Notes |
| --- | ---: | ---: | --- |
| Rejet non authentifié `/v1/chat/completions` | 174 ms | 184 ms | Inclut DNS, TCP, TLS public, traitement de requête d’enclave. |
| Connexion TCP | 55 ms | 59 ms | Chemin réseau vers `us-central1` depuis cette machine. |
| Établissement de la poignée de main TLS | 112 ms | 124 ms | Le certificat ACME public se termine à l’intérieur de l’enclave. |
| `/attestation` | 1,06 s | 1,12 s | Inclut la génération du jeton d’attestation GCP, donc non représentatif des frais généraux de routage normaux. |

Les frais généraux réseau centralisés sont bien plus élevés que les frais généraux de périphérie rapportés par OpenRouter, mais la latence des modèles domine généralement les requêtes interactives. La première étape de mise à l’échelle en production devrait être multi-région plutôt que de construire immédiatement une périphérie mondiale personnalisée.

## Forme de l’échelle horizontale

Le chemin de production est conçu pour évoluer en gardant la passerelle de prompts sans état :

- Les instances `api.trustedrouter.com` peuvent être répliquées derrière un passage TCP. Elles autorisent, réservent et règlent via le plan de contrôle, mais les octets de prompt ne quittent jamais le chemin attesté.
- Spanner stocke l’état du plan de contrôle et de facturation fortement cohérent : utilisateurs, espaces de travail, clés, métadonnées BYOK, idempotence des événements de paiement, soldes, agrégats, réservations actives et une fenêtre d’audit terminale des requêtes de 30 jours.
- Bigtable stocke des métadonnées d’activité à volume élevé et borné, indexées par espace de travail et date. L’activité et les benchmarks des fournisseurs conservent 30 jours, les échantillons synthétiques bruts conservent 14 jours et les agrégats de statut compacts conservent 24 mois. Les arguments de prompt, de sortie et d’appel d’outil ne sont pas stockés.
- La vérification des clés API utilise un hachage de recherche à haute entropie pour des lectures ponctuelles ; elle ne scanne pas les clés.
- Les limites de débit sont appliquées avant les gestionnaires de route et utilisent le magasin configuré, de sorte que les compteurs de production sont partagés entre les instances Cloud Run.

À un trafic d’échelle OpenRouter, le prochain goulet d’étranglement n’est pas le binaire d’enclave ; c’est le chemin synchrone de facturation/autorisation. L’architecture nécessite des réservations partitionnées, des clusters Bigtable régionaux, des limites de périphérie Cloud Armor et plusieurs réplicas de passerelle avant de permettre au trafic public de monter en charge.

## Plan multi-région

Le multi-région est réalisable tout en préservant la frontière de confiance, mais il doit être fait avec précaution :

- Exécuter des pools de passerelles attestées chauds indépendants dans au moins `us-central1`, `us-east4` et `europe-west4`, puis en Asie une fois les trois premières régions stables.
- Conserver les clés privées TLS à l’intérieur de chaque charge de travail Confidential Space régionale.
- Déplacer ACME de TLS-ALPN-01 vers DNS-01 ou un autre flux de défi compatible avec plusieurs points de terminaison régionaux pour le même nom d’hôte. Le flux actuel TLS-ALPN-01 convient pour une seule région, mais un enregistrement DNS mondial peut router les défis vers le mauvais réplica.
- Conserver des noms d’hôte régionaux tels que `api-us-central1.quillrouter.com`, `api-us-east4.quillrouter.com` et `api-europe-west4.quillrouter.com` pour une attestation déterministe, des tests de fumée et le basculement SDK.
- Placer `api.trustedrouter.com` derrière un DNS à latence/géo ou un passage TCP qui ne termine pas TLS. Le proxy orange-cloud de Cloudflare reste incompatible avec l’affirmation de confiance du chemin des prompts.
- Autoriser via des baux de quota régionaux, et non une transaction Spanner mondiale synchrone pour chaque requête.
- Écrire les métadonnées de génération dans des clusters Bigtable régionaux, puis les agréger dans des vues d’activité mondiales de manière asynchrone.
- Garder le routage des fournisseurs régional, avec des disjoncteurs par fournisseur, une politique de repli et des limites de débit par fournisseur.

La règle de conception clé : une panne régionale peut échouer de manière sécurisée ou router vers une autre région attestée, mais elle ne doit jamais se dégrader silencieusement vers un gestionnaire de prompt non attesté.

## Cible quatre neuf du routeur principal

La cible est un SLO interne, pas un SLA contractuel. 99,99 % autorise environ 52 minutes 36 secondes d’indisponibilité par an. Le statut public qualifie ce nombre de cible jusqu’à ce qu’au moins 30 à 60 jours de disponibilité mesurée du routeur principal à 99,99 % existent.

La disponibilité du routeur principal signifie :

- le TLS attesté est joignable ;
- la validation des clés API et l’autorisation de passerelle fonctionnent ;
- les candidats de route sont renvoyés et le repli peut choisir un fournisseur sain ;
- le règlement/remboursement est durable ou réparable en toute sécurité ;
- aucune requête de prompt ne retombe jamais sur un chemin non attesté.

Les chemins de code qui soutiennent cette feuille de route aujourd’hui sont :

- `/status.json` exporte `slo_classes.router_core`, `slo_classes.control_plane` et des alertes de taux de combustion pour les fenêtres de 5 min, 1 h, 6 h et 24 h.
- Le chien de garde de déploiement lit `router_core` par défaut, de sorte que les pannes exclusives aux fournisseurs ne font pas automatiquement reculer un déploiement du plan de contrôle.
- Les SDK sont censés réessayer les échecs de connexion et les erreurs 502/503/504 sur les points de terminaison attestés régionaux avant de signaler un échec.
- Les écritures d’activité Bigtable sont réparables à partir de la boîte d’envoi de règlement durable. Le règlement utilise des identifiants de génération déterministes, de sorte que les nouvelles tentatives écrasent les mêmes lignes d’index et ne peuvent ni double facturer ni dupliquer l’activité.

Avant de décrire quatre neuf comme une disponibilité mesurée plutôt qu’une cible, exiger trois régions GCP attestées chaudes, des pages testées, des tests de chaos du routeur principal, des déploiements régionaux par étapes avec des portes de retour arrière, et au moins 30 jours de disponibilité mesurée du routeur principal à 99,99 % ou plus.

## Contrat de passerelle interne

Le plan d’API attesté peut réserver et régler l’utilisation sans envoyer de contenu de prompt ou de sortie au plan de contrôle :

- `POST /v1/internal/gateway/authorize` : valide le hachage de clé API, réserve les crédits/limites de clé et renvoie les métadonnées de routage fournisseur/BYOK, les candidats de route dérivés des filtres de requête `model`, `models` et `provider`, ainsi que les points de terminaison régionaux configurés.
- `POST /v1/internal/gateway/settle` : règle l’utilisation réussie et ajoute des lignes d’activité de métadonnées uniquement.
- `POST /v1/internal/gateway/refund` : libère les réservations après des défaillances de fournisseur ou des déconnexions client.

Définir `TR_INTERNAL_GATEWAY_TOKEN` en dehors du développement local.

## Stockage de production

La production utilise :```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