address-validator

# 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 :

| # | Critère | Vérification |
|---|---------|--------------|
| 1 | Un appel sans preuve reçoit `402` (prix et protocole annoncés) | `tests/test_payment.py` (8 tests), `tests/test_routes_extra.py::test_metrics_count_unpaid_requests`, `scripts/e2e_check.py` |
| 2 | Un appel avec preuve valide reçoit `200` et le résultat | `tests/test_cache.py` (appels payants réels), `tests/test_validation.py::test_valid_address_with_mocked_provider`, `scripts/e2e_check.py` |
| 3 | Le cache évite de rappeler le fournisseur sur une adresse répétée | `tests/test_cache.py::test_second_identical_request_hits_cache` et `::test_distinct_requests_call_provider_twice`, `scripts/e2e_check.py` |
| 4 | Une panne fournisseur produit une réponse dégradée rapide et explicite | `tests/test_validation.py::test_degraded_flag_set_when_provider_unreachable`, `tests/test_circuit_breaker.py`, `tests/test_latency_budget.py` |

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à) — et la vérification de paiement
on-chain est **disponible mais désactivée par défaut** (D15 pour le mode par
défaut, D27 pour la couche optionnelle). Les deux sont documentés
(`README.md` §7 et §9, `SECURITY.md` §3 et §6) plutôt que passés 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).

```powershell
# 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
```

```powershell
# 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).

| Champ | Variable | Défaut | Rôle |
|-------|----------|--------|------|
| `api_host` / `api_port` | `API_HOST` / `API_PORT` | `127.0.0.1` / `8000` | écoute uvicorn (`127.0.0.1` : le service est publié par Nginx, pas directement) |
| `api_secret_key` | `API_SECRET_KEY` | `change_me` | **clé HMAC de la preuve de paiement** — à changer impérativement |
| `database_url` | `DATABASE_URL` | `postgresql://user:password@localhost:5432/address_validator` | PostgreSQL (journal des paiements) |
| `redis_url` | `REDIS_URL` | `redis://localhost:6379/0` | cache des résultats |
| `smarty_auth_id` / `smarty_auth_token` | `SMARTY_AUTH_ID` / `SMARTY_AUTH_TOKEN` | vide | identifiants du fournisseur de validation |
| `cdp_api_key_id` / `cdp_api_key_secret` | `CDP_API_KEY_ID` / `CDP_API_KEY_SECRET` | vide | SDK Coinbase CDP (facultatif) |
| `cdp_wallet_address` | `CDP_WALLET_ADDRESS` | vide | portefeuille annoncé dans le `402` |
| `x402_price` | `X402_PRICE` | `0.02` | prix par validation, en USDC |
| `x402_onchain_verify` | `X402_ONCHAIN_VERIFY` | `false` | confirmation on-chain du transfert USDC (D27) — voir §7 |
| `base_rpc_url` | `BASE_RPC_URL` | `https://mainnet.base.org` | nœud JSON-RPC Base (chaîne 8453) utilisé quand D27 est actif |
| `x402_usdc_contract` | `X402_USDC_CONTRACT` | `0x833589…4bda02913` | contrat USDC natif de Base |
| `x402_min_confirmations` | `X402_MIN_CONFIRMATIONS` | `1` | confirmations minimales exigées avant d'accepter le paiement |
| `x402_network` / `x402_chain_id` | `X402_NETWORK` / `X402_CHAIN_ID` | `base` / `8453` | reseau et chaine annonces dans `accepts[]` |
| `x402_domain_name` / `x402_domain_version` | `X402_DOMAIN_NAME` / `X402_DOMAIN_VERSION` | `USD Coin` / `2` | domaine EIP-712 du jeton - **verifie on-chain** par `scripts/test_x402_payment.py --check-domain` |
| `x402_facilitator_url` | `X402_FACILITATOR_URL` | `https://api.cdp.coinbase.com/platform/v2/x402` | facilitateur (`/verify` puis `/settle`) |
| `x402_facilitator_verify` | `X402_FACILITATOR_VERIFY` | `true` | appel de `/verify` avant le reglement |
| `x402_require_settlement` | `X402_REQUIRE_SETTLEMENT` | `true` | **ne rendre le service qu'apres encaissement** (`false` = jamais en production) |
| `public_base_url` / `mcp_public_url` | `PUBLIC_BASE_URL` / `MCP_PUBLIC_URL` | `https://kder-ai.com` / `.../mcp` | URLs publiees dans `accepts[].resource`, la carte MCP et les annuaires |
| `discovery_log_*` | `DISCOVERY_LOG_ENABLED`, `DISCOVERY_LOG_PATH`, `DISCOVERY_LOG_RAW_IP`, `DISCOVERY_LOG_SALT`, `DISCOVERY_LOG_RETENTION_DAYS` | journal actif, chemin vide (journald), IP pseudonymisee, 30 j | journal des refus `402` et retention appliquee (`PRIVACY.md` 3) |
| `dashboard_user` / `dashboard_password` | `DASHBOARD_USER` / `DASHBOARD_PASSWORD` | `kder` / vide | `/dashboard` - vide = endpoint **ferme** (`503`) |
| `test_mode` / `test_mode_cutoff_utc` | `TEST_MODE` / `TEST_MODE_CUTOFF_UTC` | `false` / `2026-10-11T12:00:00+00:00` | une transaction marquée `test_mode` est un essai de recette : exclue de `real_*`, comptée dans `test_*` et `total_*` (D40) |
| `environment` / `log_level` | `ENVIRONMENT` / `LOG_LEVEL` | `development` / `INFO` | contexte et verbosité |

## 4. Endpoints et contrat de données

| Méthode | Chemin | Rôle | Source |
|---------|--------|------|--------|
| `GET` | `/` | identité du service et liens | `app/main.py:57-65` |
| `GET` | `/manifest` | description x402 (prix, devise, schémas) | `app/routes/manifest.py` |
| `GET` | `/health` | état réel de PostgreSQL et Redis, borné à 2 s | `app/routes/health.py` |
| `GET` | `/metrics` | compteurs, état du disjoncteur, état du cache | `app/routes/metrics.py` |
| `GET` | `/metrics/revenue` | revenu agrégé 24 h / 7 j / 30 j — `real_*` hors recette, `total_*` registre entier (D40) — et disponibilité du registre | `app/routes/revenue.py` |
| `GET` | `/dashboard` | tableau de bord d'exploitation — **privé** (Basic Auth ; `503` si `DASHBOARD_PASSWORD` est absent) | `app/routes/dashboard.py` |
| `POST` | `/validate` | **payant** — validation complète | `app/routes/validate.py` |
| `GET` | `/docs` | documentation interactive (FastAPI) | auto |
| `GET` | `/llms.txt`, `/AGENTS.md`, `/.well-known/security.txt` | fichiers de découverte pour agents, servis en statique par Nginx (voir `DISCOVERY.md`) | `nginx-discovery.conf` |
| `POST` | `/mcp` | serveur MCP (JSON-RPC 2.0) : decouverte gratuite, `tools/call` **payant** | `app/routes/mcp.py` |
| `GET` | `/.well-known/mcp-server` | carte de decouverte MCP (servie par l'application) | `app/routes/mcp.py` |

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 :

| Champ | Contenu |
|-------|---------|
| `real_validations_paid`, `real_revenue_usdc` | ce qu'un **client** a payé — le chiffre publiable |
| `total_validations_paid`, `total_revenue_usdc` | tout le registre, essais de recette compris (audit) |
| `test_validations_paid`, `test_revenue_usdc` | ce qui est exclu du réel, chiffré : `real_*` + `test_*` = `total_*` |

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