Simpl-Resultat/docs/adr/0009-proxy-price-fetching-via-maximus-api.md

ADR 0009 — Price-fetching premium via proxy maximus-api

• Status: Accepted (architecture documentée — implémentation reportée à l'Issue #143, BLOCKED par maximus-api Phase 2)
• Date: 2026-04-25
• Milestone: overnight-2026-04-26-bilan (architecture spec)

Context

La feature Bilan supporte des comptes "priced" (actions, crypto) où chaque ligne de snapshot stocke (quantity, unit_price, value). La saisie manuelle de unit_price reste toujours possible mais devient pénible dès qu'on a plusieurs titres ou qu'on rétro-saisit un historique.

L'objectif est de proposer un bouton "récupérer le prix au [date]" qui interroge un fournisseur de données (Yahoo Finance, CoinGecko, etc.) sans trahir le principe privacy-first NON NÉGOCIABLE du projet :

Zéro donnée envoyée vers un serveur tiers. Tout le traitement CSV et toutes les données financières restent en local. Aucune télémétrie, aucun analytics cloud.

Or interroger Yahoo ou CoinGecko, c'est par définition envoyer une requête sortante depuis l'IP de l'utilisateur. Quelles informations fuiteraient ?

• L'IP de l'utilisateur : géolocalisation grossière, profilage de session
• L'User-Agent par défaut de reqwest : reqwest/0.12 ..., identifie le client comme une app Tauri (silhouette technique reconnaissable)
• Le symbole + date : "AAPL au 2026-03-15" n'est pas identifiant en soi mais corrélé à l'IP, le provider peut reconstruire le portefeuille
• Headers résiduels : Accept-Language peut révéler la locale système

Trois architectures candidates :

Option	Privacy	Complexité serveur	Coût d'API
Appel direct client → provider	❌ IP exposée, fingerprint headers	aucune	par user (rate limits triggered fast)
Appel direct + Tor / VPN intégré	⚠ partiel, latence dégradée	aucune	par user
Proxy via maximus-api auto-hébergé	✅ IP cachée, headers strippés, cache mutualisé	Endpoint /v1/prices à maintenir	mutualisé (cache mutualisé entre users premium)

Decision

Implémenter le price-fetching comme fonctionnalité premium-only servie par maximus-api agissant comme proxy, avec consentement explicite et hygiène de headers stricte des deux côtés du fil.

Architecture

[App Tauri]
    │  GET /v1/prices?symbol=AAPL&date=2026-03-15
    │  Headers: Authorization: Bearer <activation_token>
    │           Accept: application/json
    │           User-Agent: simpl-resultat
    ▼
[maximus-api]                              ← VPS Max (Coolify)
    │  1. Strip TOUS headers entrants identifiants
    │  2. Validation tier premium (403 si non-premium)
    │  3. Cache SQLite (symbol, date) → price (TTL infini sur dates passées)
    │  4. Cache miss → adapter (Yahoo / CoinGecko)
    ▼
[Provider tiers]                           ← voit l'IP du VPS, pas du client

Choix de providers : abstraction adapter

Côté maximus-api, un module price-fetcher expose une interface unique et délègue à des adapters :

Provider	Stocks	Crypto	Coût	Adapter
Yahoo Finance (unofficial)	✅	⚠	gratuit	YahooAdapter (HTTP direct)
CoinGecko	❌	✅ excellent	gratuit (free tier 30 req/min)	CoinGeckoAdapter
Alpha Vantage (fallback)	✅	⚠	freemium	optionnel si Yahoo casse

Stocks → Yahoo ; Crypto → CoinGecko. L'abstraction permet de swap si un provider casse, sans changer le contrat client.

Stratégie d'authentification

• Authorization: Bearer <activation_token> uniquement. Le token est lu côté client depuis activation_path (le fichier déjà utilisé par license_commands.rs pour persister le token d'activation). Jamais stocké dans user_preferences (la table SQL de l'app n'a pas vocation à versionner les credentials).
• Jamais en query string. Un token-in-URL leakerait dans :
  • Les logs Traefik / nginx du VPS (URL complète loguée par défaut)
  • Le header Referer si maximus-api redirige
  • Les écrans de partage (le header Authorization est masqué par les outils de capture, pas l'URL)

Hygiène des headers — privacy en profondeur

Côté client (Rust / reqwest) :

• reqwest::Client::builder().user_agent("simpl-resultat").build() — UA fixe, pas le default reqwest/0.12 ...
• Headers envoyés UNIQUEMENT : Authorization: Bearer <token> + Accept: application/json
• Pas de Accept-Language (révèle la locale)
• Pas d'autres headers identifiants

Côté serveur (maximus-api) :

• Strip TOUS les headers entrants avant de proxyer vers le provider tiers (X-Forwarded-For, User-Agent client, Accept-Language, etc.)
• Ne JAMAIS logger (symbol, license_id) ensemble. Soit séparer les logs (un journal pour la facturation/quota par licence sans symbole, un journal pour les hits cache/provider sans license), soit hasher le license_id côté serveur avec un sel rotatif court avant log
• Validation premium AVANT cache et provider — un client non-premium reçoit 403 sans qu'aucun appel sortant ne soit déclenché

Rate limiting

Côté client :

• Max 1 fetch / 2 secondes (timer simple)
• Dedup in-flight par (symbol, date) (deux clics rapides = 1 seule requête réseau)
• Backoff exponentiel sur 5xx / network : 2s, 4s, 8s — max 3 retries
• Plafond hard : 100 fetches par session snapshot (anti-loop)

Côté serveur :

• Quota par licence (proposition initiale : 1000 req/jour, le cache absorbe l'essentiel)
• Le cache (symbol, date) est immuable pour les dates passées (TTL infini), 5 min pour today (le marché peut bouger)

Premium gating — défense en profondeur

• UI client : si entitlements.check_entitlement("price-fetching") retourne false, le bouton ↻ affiche un tooltip "Disponible avec abonnement" et est désactivé. Pas de tentative de fetch.
• Server-side : maximus-api /v1/prices valide le tier premium AVANT cache/provider. Un client modifié qui bypass la UI reçoit 403.

La double vérification est délibérée : le client est compromettable (l'app Tauri est ouverte au reverse-engineering), seul le serveur peut faire foi.

Consentement explicite (per-profile)

• Stockage : user_preferences.price_fetching_consent = {consented_at: <ISO>, version: 1}
• NE PAS seeder la clé. Absence = jamais demandé. Le default doit être "non-décidé", pas "false".
• Premier clic sur le bouton ↻ → modal de consentement → écriture de la clé après acceptation
• Permanence : pas de re-consent automatique. Révocation explicite via toggle Settings (supprime la clé)
• Stockage per-profile (table user_preferences est par-profil), pas global au système

Mode offline / fallback

L'app ne doit jamais bloquer la saisie d'un snapshot parce que le price-fetching a échoué. La saisie manuelle de unit_price reste TOUJOURS disponible :

Erreur serveur	Comportement
401 license expirée	Toast "Renouvelez votre abonnement" + champ manuel dispo
403 non-premium	Toast "Disponible avec abonnement Premium" + champ manuel dispo
404 symbole	Toast "Symbole introuvable — vérifiez l'orthographe" + champ manuel
429 rate limit	Toast "Limite atteinte — réessayez plus tard" + champ manuel
Network error / 5xx	Toast "Service temporairement indisponible" + champ manuel

Consequences

Positive

• L'IP de l'utilisateur n'est JAMAIS exposée à Yahoo / CoinGecko. Le provider voit l'IP du VPS de Max — privacy-first préservée.
• Aucun symbole ne révèle de données personnelles. "AAPL" ou "BTC" ne sont pas identifiants en soi ; corrélés à une license_id ils le redeviennent, c'est pourquoi le serveur ne logue jamais les deux ensemble.
• Cache mutualisé. Si 500 utilisateurs premium demandent AAPL au 2026-03-15, c'est UN seul appel sortant côté maximus-api. Économise les rate limits ET réduit la surface d'exposition.
• Mode offline préservé. L'app continue de fonctionner sans price-fetching — la saisie manuelle reste le chemin de secours.
• Justification commerciale. Le price-fetching premium aligne le coût d'API tiers sur la révenue récurrente, sans dégrader l'expérience free-tier (qui reste 100 % local).
• Adapter pattern. Si Yahoo casse (API non officielle), swap pour Alpha Vantage côté serveur sans changer le contrat client.

Negative / trade-offs

• Dépendance opérationnelle au VPS. Si maximus-api est down, le price-fetching ne fonctionne pas — atténué par le fallback manuel toujours dispo.
• Surface serveur à maintenir. Endpoint /v1/prices + cache + adapters + auth + rate limiting + observabilité (sans corrélation log).
• Charge financière sur Max. Les tier free n'ont pas accès, donc les coûts d'API tiers sont absorbés par les abonnements premium ; le cache aide significativement.
• Implémentation BLOQUÉE. L'Issue #143 ne peut shipper tant que maximus-api Phase 2 n'expose pas /v1/prices (dépendance externe : issues maximus-api #49 license server core et #136 Stripe webhooks).

Alternatives considered

• Appel direct client → provider. Rejeté : viole le principe privacy-first (IP exposée + fingerprint headers).
• Tor / I2P intégré. Rejeté : latence prohibitive (5-10 secondes par fetch), maintenance d'un client Tor embarqué dans Tauri, et certains providers bloquent les exits Tor.
• VPN tiers (Mullvad, etc.) configuré par l'utilisateur. Rejeté : ne supprime pas le fingerprint headers, et "exiger l'utilisateur à configurer un VPN" est une régression UX inacceptable.
• Cache local sans serveur (chaque user a son propre cache). Rejeté : pas de mutualisation, chaque user paie son propre rate limit, et le client doit toujours faire l'appel sortant initial (donc IP exposée).
• Saisie manuelle uniquement, pas de price-fetching du tout. C'est le mode free-tier — fonctionnel mais friction élevée pour les utilisateurs avec un portefeuille actions/crypto significatif. Le proxy premium est le compromis qui justifie l'abonnement sans dégrader le free-tier.
• Endpoint /v1/symbols/search côté maximus-api pour autocomplete. Reporté à v2 : l'autocomplete double la surface d'API et n'est pas critique. La saisie texte simple suffit au MVP.

References

• Spec : spec-decisions-bilan.md, spec-plan-bilan.md (Issue #5 — Phase 5)
• Spike : ~/claude-code/.spikes/bilan/code/price-fetching.md (architecture, choix providers, consent flow)
• Issue client (BLOCKED) : maximus/simpl-resultat #143
• Issues maximus-api (externes, prerequisites) : maximus-api#49 (license server core), maximus-api#136 (Stripe webhooks)
• Pattern auth : src-tauri/src/commands/license_commands.rs (activation_path + activate_machine — le token Bearer existe déjà)
• Privacy frame : ce que maximus-api voit jamais ensemble = (IP, license_id, symbol). Le proxy garantit que (IP) est cachée du provider et que (license_id, symbol) ne se retrouvent pas dans le même log.