Address Validator README

Address Validator API

API HTTP payante à la requête (protocole x402, prix par défaut 0.02 USDC) qui prend une adresse de livraison brute et renvoie une adresse standardisée, ses coordonnées, un score de livrabilité et une clé de cache.

1. Présentation

• Entrée unique payante : POST /validate — refuse en 402 Payment Required tant qu'aucune preuve de paiement valide n'est fournie.
• Sortie : adresse standardisée (line1, line2, city, state, zip, country), latitude/longitude (géocodage Nominatim), deliverability, confidence, degraded et cache_key.
• Découverte : GET /manifest décrit le service et son schéma pour un annuaire x402 / MCP.
• Résilience : si le fournisseur est injoignable, l'API répond quand même 200 avec degraded: true — jamais une erreur qui laisserait croire à une adresse invalide certaine.

Critères de succès de la spec, et où ils sont vérifiés automatiquement :

Ce que ce service ne fait pas : aucun rate limiting applicatif (D21) — la limite est tenue au niveau edge par Nginx (nginx-hardening.conf : 10 requêtes/s par IP, rafale 20, 429 au-delà). Le paiement hérité (preuve HMAC à secret partagé, D15) n'est plus accepté sur sa seule signature : depuis le durcissement W1 (12/10/2026), la confirmation on-chain (D27) est active par défaut et exige, sur Base, un transfert USDC confirmé vers le portefeuille d'encaissement. Une preuve HMAC synthétique n'obtient un 200 que dans une recette déclarée (TEST_MODE=true), et la ligne écrite est alors marquée test_mode, donc exclue du revenu réel (D40). Tout est documenté (README.md §7 et §9, SECURITY.md §3 et §6, AUDIT_TRAFIC_VPS.md §5) plutôt que passé sous silence.

2. Démarrage rapide

Prérequis : Python 3.12 (le venv du dépôt tourne en 3.12.10, comme l'image python:3.12-slim du Dockerfile). PostgreSQL et Redis sont facultatifs : sans eux, l'API démarre et se dégrade proprement (/health le dit).

# 1. Environnement virtuel
py -3.12 -m venv .venv
.\.venv\Scripts\python.exe -m pip install -r requirements.txt -r requirements-dev.txt

# 2. Configuration (jamais de secret dans le dépôt)
Copy-Item .env.example .env        # renseigner SMARTY_AUTH_ID / API_SECRET_KEY / clés CDP

# 3. Lancer l'API
.\.venv\Scripts\python.exe -m uvicorn app.main:app --reload --port 8000

# Vérifications
.\.venv\Scripts\python.exe -m pytest -q                  # suite complète
.\.venv\Scripts\python.exe scripts\run_tests.py          # oracle de tests (rapport JUnit)
.\.venv\Scripts\python.exe scripts\doc_check.py README.md 10   # sections de ce fichier
.\.venv\Scripts\python.exe scripts\e2e_check.py http://127.0.0.1:8000   # recette bout-en-bout

Démarrage conteneurisé : docker compose up -d (voir docker-compose.yml et Dockerfile).

Déploiement en production (VPS Debian 12, Nginx + HTTPS, paiement x402) : DEPLOIEMENT_VPS.md — compte rendu réel, écarts assumés par rapport au plan et points de vigilance d'exploitation.

3. Configuration

Toutes les valeurs viennent de l'environnement ou de .env (pydantic-settings, app/config.py). Une variable inconnue est ignorée (décision D8).

4. Endpoints et contrat de données

Chaque requête refusée en 402 est journalisée sous forme de métadonnées (horodatage, endpoint, User-Agent, IP pseudonymisée) : jamais l'adresse validée. Réglages et rétention : PRIVACY.md §3, DISCOVERY.md §4.

4.1 Revenu réel contre revenu du registre (D40)

/metrics/revenue publie trois lectures du même registre, jamais mélangées :

Les alias validations_paid et revenue_usdc (D31) pointent sur le réel. Une transaction est marquée test_mode de deux façons, et de deux seulement : TEST_MODE=true au moment où le service l'enregistre (recette en cours), ou scripts/migrate_test_mode.py pour les lignes déjà écrites — seuil TEST_MODE_CUTOFF_UTC (défaut 2026-10-11T12:00:00+00:00, les deux essais de recette de ce jour-là). Rien n'est déduit du montant ni de l'adresse : une ligne non marquée reste du revenu réel. /dashboard affiche le réel en avant et la recette dans sa propre carte.

Sur un registre déjà écrit, le rattrapage se fait sans redéploiement : venv/bin/python scripts/migrate_test_mode.py (simulation, ligne par ligne) puis --apply. Le rejeu n'écrit plus rien (idempotent) ; le résultat se contrôle avec curl -s http://127.0.0.1:8000/metrics/revenue.

Requête (app/schemas.py:11-16) : {"address": {"street", "city", "state", "zip", "country"}} — country vaut US par défaut, les autres champs sont obligatoires (un champ manquant donne 422).

Réponse (app/schemas.py:19-37) : {"result": {"validated", "standardized", "latitude", "longitude", "deliverability", "confidence", "degraded", "cache_key"}, "price_paid", "transaction_id"}.

Pipeline de validation (app/validation/__init__.py:26-41) : parse → standardize → verify (fournisseur) → geocode → score.

4.2 Deux façons de payer la même validation (D45)

POST /validate sert deux clients : la boutique abonnée, qui présente sa clé API, et l'agent autonome, qui paie à l'appel (§5). La clé a la priorité : si les deux sont envoyés, l'abonnement tranche et l'appel n'est pas encaissé en USDC.

La réponse porte X-Payment-Mode (api_key, x402 ou hmac) : sans lui, un client ne peut pas distinguer un appel couvert par son abonnement d'un appel encaissé. En mode clé, deux en-têtes disent aussi l'état du compte — X-Plan et X-Quota-Remaining (absent pour un plan illimité, l'absence dit « illimité »).

Le quota est mensuel, comme publié sur /pricing : la fenêtre est le mois calendaire UTC (accounts.month_start()), le compteur à vie reste affiché dans /compte mais ne ferme aucune porte. Les corps de refus sont identifiables ({"mode": "api_key", "reason": "cle_inconnue" | "compte_expire" | "quota_atteint"}), ne contiennent que le préfixe de la clé (sk_live_ab12) et indiquent la sortie (upgrade → /pricing).

$cle = "sk_live_..."   # affichée une seule fois à l'inscription, régénérable sur /compte
$corps = '{"address":{"street":"1 Rue de Paris","city":"Saint-Denis","state":"RE","zip":"97400","country":"RE"}}'
$r = Invoke-WebRequest -Uri http://127.0.0.1:8000/validate -Method POST `
     -Headers @{ "X-API-Key" = $cle } -ContentType "application/json" -Body $corps
$r.Headers["X-Payment-Mode"], $r.Headers["X-Plan"], $r.Headers["X-Quota-Remaining"]
$r.Content | ConvertFrom-Json | Select-Object price_paid, transaction_id
# -> api_key  trial  99 ; price_paid = 0.0, transaction_id = $null

Un même appel sans en-tête X-API-Key reste facturé en x402 : le mode clé n'a rien retiré aux agents autonomes. Compteurs publiés par /metrics : api_key_requests, api_key_validations, api_key_denied, api_key_unavailable.

4.3 Essai gratuit public (D46)

GET /validate-form sert une page publique — indexable, cachable 5 minutes, et autonome : aucun script, aucune ressource externe, la feuille de style partagée (app/web.py). C'est la première page qu'un visiteur voit ; la CSP (form-action 'self') rend vérifiable par le navigateur ce que le code promet.

Compteurs du plafond visibles dans /metrics : un refus de plafond compté est la seule façon de distinguer « personne n'essaie » de « tout le monde est bloqué ».

4.4 Guide d'intégration public (D48)

GET /guide répond à la question que se pose un client qui vient de recevoir sa clé : authentification (X-API-Key ou x402), contrat JSON exact, les huit codes de retour avec l'action à mener, ce qui est mis en cache et ce qui est plafonné, puis quatre cas pratiques (appel direct PowerShell, import CSV en Python, Shopify, WooCommerce).

4.5 Email de bienvenue d'une boutique (D49)

Pas une page, un message : celui qu'on envoie à la boutique qui vient de créer son compte. Il vit dans EMAIL_BIENVENUE.md, sous deux formes — le gabarit à charger dans n8n (variables {{…}}, expliquées dans une table) et un exemplaire prêt à envoyer pour le premier client (Tiitoune Art).

4.6 Suivi des clients (D50)

Un tableau de suivi ne vaut que par son accord avec ce qui est réellement servi. Ce que la table des comptes contient déjà répond à la seule question qui décide du revenu : quels comptes existent, lesquels se perdent en silence, et que faut-il leur dire ? Les règles vivent dans app/suivi.py (états, seuils, ordre d'urgence), l'exécution dans scripts/suivi_clients.py.

# rapport lisible, sur la base de la configuration (DATABASE_URL)
.\.venv\Scripts\python.exe scripts\suivi_clients.py

# export pour un tableur, seuils resserrés
.\.venv\Scripts\python.exe scripts\suivi_clients.py --format csv --sortie suivi.csv --essai-bientot-jours 5

# expliquer après coup un classement : rejouer le rapport à une date donnée
.\.venv\Scripts\python.exe scripts\suivi_clients.py --maintenant 2026-10-01T09:00:00+00:00

Vérification : .\.venv\Scripts\python.exe scripts\decisions_check.py D50 — la porte installe une base réelle et compare l'état publié au refus que la route applique, y compris le cas du client payant dont la date d'essai est passée.

4.7 Page d'accueil (D53)

GET / sert la vitrine à un navigateur et garde le JSON d'avant pour un programme (Vary: Accept sur les deux). Le dessin vit dans app/templates/accueil/fr.html (maquette d'origine : docs/maquettes/page-accueil/) ; ses chiffres (essai, quotas, prix, prix x402, contact) sont injectés par app/routes/accueil.py depuis le code et la configuration.

curl.exe -s https://kder-ai.com/                      # JSON, comme avant
curl.exe -s -H "Accept: text/html" https://kder-ai.com/   # la vitrine

Vérification : .\.venv\Scripts\python.exe scripts\decisions_check.py D53.

4.8 Six langues (D57)

Le français reste à la racine ; les cinq autres langues ont leur préfixe. Toutes les pages publiques existent dans les six : la vitrine, le guide (D58), l'essai gratuit (D59), les tarifs (D60), l'inscription et l'espace client (D61), chacune à son adresse française précédée du préfixe de la langue (/en/guide, /ar/signup…).

app/i18n.py fabrique les adresses (chemin(lang, page)), les nombres et les prix de chaque langue (prix, mention_euros, taux de septembre 2026) et rend les gabarits (rendre). Les montants en euros viennent d'accounts.OFFRES (aussi lisibles sous pricing.OFFRES) : changer un prix sans refaire la table convertie fait échouer tests/test_i18n.py et la porte D57. Les photos sont servies par l'application sous /images/ : la CSP publique n'ouvre que img-src 'self'.

curl.exe -s https://kder-ai.com/en/                              # la vitrine en anglais
curl.exe -sI https://kder-ai.com/images/commercante-colis.jpg    # image/jpeg, nosniff

Vérification : .\.venv\Scripts\python.exe scripts\decisions_check.py D57.

5. Exemple d'appel payant

1. Construire une preuve (le client et l'API partagent API_SECRET_KEY) :

.\.venv\Scripts\python.exe -c "from app.payment import build_payment_proof; print(build_payment_proof('0x-demo-tx'))"
# -> 0x-demo-tx:1770000000.123:<hmac_sha256_hex>

2. Appeler l'API :

curl.exe -X POST http://127.0.0.1:8000/validate `
  -H "Content-Type: application/json" `
  -H "X-Payment-Proof: 0x-demo-tx:1770000000.123:<hmac>" `
  -H "X-Transaction-Id: 0x-demo-tx" `
  -d "{\"address\":{\"street\":\"1600 Amphitheatre Parkway\",\"city\":\"Mountain View\",\"state\":\"CA\",\"zip\":\"94043\",\"country\":\"US\"}}"

3. Sans preuve, ou avec une preuve périmée / malformée / falsifiée, la réponse est 402 (app/payment.py:77-85) :

{"error": "Payment Required", "price": 0.02, "currency": "USDC",
 "wallet": "", "protocol": "x402", "version": "1.0"}

4. Avec une preuve valide, la réponse est 200. Exemple mesuré en recette le 10/10/2026 sur ce poste (fournisseur injoignable, donc degraded) :

{"result": {"validated": false, "standardized": {"line1": "1600 Amphitheatre Parkway", "...": "..."},
            "deliverability": "invalid", "confidence": 0.05, "degraded": true,
            "cache_key": "8f1c…"},
 "price_paid": 0.02, "transaction_id": "0x-demo-tx"}

transaction_id reflète simplement l'en-tête X-Transaction-Id reçu (app/routes/validate.py:67).

Même appel en production le 11/10/2026 (https://kder-ai.com, fournisseur réel actif, preuve HMAC valide) :

{"result": {"validated": true, "deliverability": "residential", "confidence": 1.0,
            "degraded": false, "cache_key": "250a6087…"},
 "price_paid": 0.02, "transaction_id": null}

deliverability est dérivé du code DPV renvoyé par le fournisseur (Y → residential, scorer.py:17-23) et confidence intègre le bonus de géocodage (0,99 + 0,05, borné à 1,0). Le metadata.rdi du fournisseur (Commercial sur cette adresse) reste dans la charge brute, non exposée par l'API.

6. Cache, résilience et budget de latence

Latences mesurées sur ce poste le 10/10/2026 (PostgreSQL et Redis éteints, réseau sortant actif, identifiants fournisseur vides donc réponse 401) :

Ces chiffres sont honnêtes et non flatteurs : la latence dégradée est dominée par le fournisseur, dont les erreurs 4xx sont rejouées par le back-off (voir TEST_REPORT.md, « Limites connues »). Les valeurs de référence enregistrées dans le code (15,2 s avant D23, 6,03 s avant D22) n'ont pas été re-mesurées aujourd'hui : elles sont citées comme historique dans TEST_REPORT.md.

7. Paiement x402 : ce qui est vérifié, réglé, et ce qui reste hérité

Le service parle x402 v1 (spécification specs/transports-v1/http.md du dépôt coinbase/x402) et règle réellement les paiements en USDC sur Base. Le corps du 402 est un document PaymentRequired :

{ "x402Version": 1, "error": "...", "accepts": [ { "scheme": "exact",
  "network": "base", "maxAmountRequired": "20000", "asset": "0x833589…2913",
  "payTo": "0x0fe9…d339", "resource": "https://kder-ai.com/validate",
  "mimeType": "application/json", "maxTimeoutSeconds": 300,
  "extra": { "name": "USD Coin", "version": "2" } } ] }

Le client renvoie sa signature dans X-PAYMENT (base64 d'un PaymentPayload {signature, authorization:{from,to,value,validAfter,validBefore,nonce}}) et reçoit X-PAYMENT-RESPONSE (base64 de {success, transaction, network, payer}).

Deux contrôles, dans cet ordre (app/x402.py) :

1. local, hors ligne — le digest EIP-712 (TransferWithAuthorization, EIP-3009) est recalculé explicitement (eth_abi, eth_hash, eth_keys), la signature récupérée est comparée à authorization.from, et destination, montant, jeton, réseau et fenêtre de validité sont confrontés à l'offre publiée. Rien ne sort du serveur avant que ce contrôle passe ;
2. règlement — POST /verify puis POST /settle au facilitateur (défaut : celui de Coinbase, authentifié par un JWT CDP signé avec CDP_API_KEY_ID / CDP_API_KEY_SECRET). Le hash du règlement alimente le registre durable (D29) ; tout échec (refus explicite, panne, hash absent, nonce déjà réglé) vaut un refus.

Le domaine EIP-712 annoncé (extra.name / extra.version) est celui du contrat : scripts/test_x402_payment.py --check-domain le vérifie on-chain — mesuré le 11/10/2026 sur Base : name() = "USD Coin", version() = "2", decimals() = 6.

Ce qui reste hérité (D15). L'en-tête X-Payment-Proof (tx_hash:timestamp:hmac_sha256) reste accepté pour l'outillage de l'exploitant et les clients déjà intégrés : fenêtre symétrique de 300 s, HMAC comparé en temps constant, et confirmation obligatoire du reçu sur Base (D27, active par défaut ; seule une recette déclarée TEST_MODE=true s'en passe) par lecture JSON-RPC (app/onchain.py, sans paquet web3 ni paquet de magasin de clés). Un paiement HMAC n'est jamais présenté comme un règlement x402 : il ne porte pas X-PAYMENT-RESPONSE.

MCP. Le même outil est exposé en MCP sur POST /mcp (JSON-RPC 2.0, sans état, sans flux SSE) : tools/list est gratuit, tools/call est payé par le même en-tête X-PAYMENT et rend structuredContent + content. La carte GET /.well-known/mcp-server est servie par l'application, donc elle ne peut pas décrire un endpoint éteint. Publication annuaire : server.json, .mcp.json, smithery.yaml (voir DISCOVERY.md §1).

Recette réelle. scripts/test_x402_payment.py a trois modes : plan (vérifie que /manifest, le corps 402 et la carte MCP publient la même offre), --check-domain (compare le domaine annoncé au contrat on-chain) et --pay (paiement réel ; exige un portefeuille acheteur financé en USDC sur Base et dépense 0,02 USDC).

8. Tests et vérification

Résultats mesurés le 10/10/2026 sur ce poste : 46 tests collectés — 45 passés, 1 ignoré (le test ignoré est un test d'intégration qui exige de vrais identifiants SmartyStreets et le réseau) ; scripts/e2e_check.py → 22/22 vérifications OK. Détail complet, méthode et limites dans TEST_REPORT.md.

Comment jouer le ledger, depuis la racine du projet :

node .cline\skills\unlazy\scripts\gate-lint.mjs address-validator\GATES.md
node .cline\skills\unlazy\scripts\gate-check.mjs --status  address-validator\GATES.md   # lit, n'exécute rien
node .cline\skills\unlazy\scripts\gate-check.mjs --approve address-validator\GATES.md   # approuve après lecture
node .cline\skills\unlazy\scripts\gate-check.mjs           address-validator\GATES.md   # exécute les oracles approuvés

9. Déploiement

deploy.sh cible un VPS Debian/Ubuntu et enchaîne : installation des paquets (python3.12, PostgreSQL, Redis, Nginx, Certbot), clone dans /opt, environnement virtuel, pip install -r requirements.txt, création de la base et de l'utilisateur PostgreSQL, activation de Redis, copie de nginx.conf, obtention du certificat (certbot --nginx), puis installation et démarrage du service systemd. Le script est en set -euo pipefail (D20) : il s'arrête à la première erreur.

Point d'attention : deploy.sh ne crée aucun fichier .env. Sans étape manuelle, le service démarre avec les valeurs par défaut — donc API_SECRET_KEY=change_me, le mot de passe PostgreSQL change_me, et aucun identifiant SmartyStreets (le fournisseur répond alors 401 et toutes les réponses sont dégradées). À faire immédiatement après le déploiement :

# sur le serveur, dans /opt/address-validator
cp .env.example .env        # puis renseigner API_SECRET_KEY, SMARTY_*, DATABASE_URL, REDIS_URL
systemctl restart address-validator
systemctl status address-validator
curl -s http://127.0.0.1:8000/health
journalctl -u address-validator -n 50

Variante conteneurisée : docker compose up -d (Dockerfile basé sur python:3.12-slim, docker-compose.yml pour l'API et ses dépendances).

Déploiement du VPS de production (kder-ai.com) : scripts/deploy-kder-ai.sh — le script réellement exécuté sur le serveur, versionné ici (avant le 11/10/2026 il ne vivait que sur le poste de travail et dans /opt, donc hors du contrôle de version). Il reprend les 11 étapes ci-dessus et ajoute :

• le refus de déployer si API_SECRET_KEY vaut encore change_me ou fait moins de 32 caractères, ou si le .env est en CRLF ;
• l'installation de nginx-hardening.conf dans /etc/nginx/conf.d/ : HSTS (1 an, includeSubDomains), X-Content-Type-Options: nosniff, Referrer-Policy: no-referrer, limit_req 10 req/s par IP (rafale 20) et corps de requête borné à 16 ko. C'est volontairement hors du vhost, que certbot --nginx réécrit à chaque renouvellement ;
• des contrôles qui échouent (ou signalent) si le durcissement a disparu : écoute de 127.0.0.1:8000 uniquement (10.6), en-têtes de sécurité (10.7), 429 sur 60 appels simultanés (10.8) ;
• la compilation de Python 3.12 en repli quand le dépôt Debian n'en fournit pas.

Le compte rendu du déploiement réel (versions, journaux, écarts assumés, correctifs du 11/10/2026) est dans DEPLOIEMENT_VPS.md.

Après mise en production : restreindre /metrics et /docs, activer un mot de passe Redis, et vérifier que Nginx a bien installé la redirection HTTPS (SECURITY.md §4 et §6).

10. Limites connues et suite

Suite recommandée, par ordre de valeur :

1. Ne retenter que les erreurs réseau et 5xx du fournisseur : supprime le back-off sur 401 et ramène la latence dégradée sous ~3 s.
2. Consommer les preuves de paiement (anti-rejeu) et refuser le démarrage si API_SECRET_KEY est resté à sa valeur par défaut.
3. Brancher les métriques sur une supervision réelle et générer le .env au déploiement.