SQLite x402 Gateway 🔐💾

Transformez n'importe quelle base SQLite (ou PostgreSQL) en API monétisée à la requête, en une seule commande.

Basé sur le protocole ouvert x402 (paiement via le code HTTP 402 Payment Required), pensé pour l'économie naissante des agents IA.

🆚 En quoi c'est différent de ce qui existe déjà

	SDK x402 officiel (Coinbase)	SQLite x402 Gateway
Écrire les routes à la main	Oui, requis	Non — auto-détectées depuis votre base
Installation de base	~500 paquets	~70 paquets (juste Express)
Mode démo sans crypto	Non	Oui, wallet et paiements simulés
Vrai paiement testnet	À configurer soi-même	npm run generate-wallet et c'est parti
Multi-base de données	Non	SQLite (natif) + PostgreSQL (optionnel)
Multi-réseau blockchain	Oui, manuel	Configurable en un champ (x402RealMode.network)
Cache / pagination / rate limiting	Non inclus	Inclus par défaut
CLI / Docker / SDK client	Non	Les trois inclus

🎯 Démarrage rapide

npm install
npm start

⭐ Fonctionnalité phare : auto-monétisation d'une base existante

node scripts/monetize.js /chemin/vers/votre-base.db
npm start

🧩 Toutes les fonctionnalités (v2)

Cœur du protocole

• Simulation x402 complète (402 → preuve de paiement → vérification → données)
• Mode réel testnet (Base Sepolia, vrai SDK Coinbase x402-express, zéro argent réel) : npm install x402-express x402-fetch
• Multi-réseaux en mode réel : base-sepolia, base (mainnet réel ⚠️), polygon, solana selon support du facilitateur
• Schéma "upto" (paiement variable selon ressources consommées) — simulé, pour expérimenter avec cette partie avancée du protocole

Bases de données

• SQLite natif (node:sqlite, zéro dépendance) par défaut
• PostgreSQL optionnel (npm install pg, database.type: "postgres")
• Auto-détection de schéma avec description de routes enrichie à partir des noms de colonnes

Performance & robustesse

• Cache de requêtes en mémoire (TTL configurable, désactivable)
• Pagination (?page=&limit=) validée strictement (pas de valeurs négatives/absurdes)
• Rate limiting par IP (fenêtre glissante, configurable)
• En-têtes de sécurité basiques (X-Frame-Options, X-Content-Type-Options...)
• Tests automatisés (npm run test:unit, node:test natif, 14 tests)

Intégrations & observabilité

• Webhooks (Slack, Discord, ou tout endpoint HTTP) à chaque transaction
• Documentation OpenAPI 3.0 auto-générée (/openapi.json) — utile pour la découverte automatique par des agents IA
• Dashboard admin avec graphique de revenus sur 7 jours, transactions, routes populaires

Expérience développeur

• CLI (node bin/cli.js start|monetize|test|..., prête pour publication npx sqlite-x402-gateway)
• Docker / Docker Compose (docker compose up)
• SDK client (packages/client) pour consommer une gateway sans réécrire la logique 402
• Gestion sécurisée des clés : .env pour les clés privées, jamais dans config.json, jamais commité

🌍 v2 — Infrastructure de paiement M2M mondiale

La v2 fait passer le projet d'un MVP pédagogique à une base d'infrastructure de paiement autonome pour agents IA, pensée pour coexister avec Stripe/PayPal/Visa/Mastercard plutôt que les remplacer.

Nouveautés v2

• Authentification M2M décentralisée : HMAC-SHA256 partagé ou signatures asymétriques Ed25519 (src/security/hmac-auth.js), avec anti-rejeu (nonce + timestamp).
• Multi-bases agnostique : SQLite, PostgreSQL, MySQL/MariaDB (src/db-adapters/mysql-adapter.js) et MongoDB (src/db-adapters/mongodb-adapter.js), unifiées derrière src/db-adapters/db-interface.js.
• Pagination par curseur (keyset) universelle (src/pagination/keyset-pagination.js), pour les grosses tables.
• Validation stricte par liste blanche des identifiants SQL découverts dynamiquement (src/security/whitelist-validator.js) — défense en profondeur anti-injection, en complément des requêtes préparées.
• Paiements hybrides : Stripe Connect (fiat, src/payments/stripe-adapter.js) et Bitcoin Lightning Network (LNbits/Alby/LND, src/payments/lightning-adapter.js), unifiés par src/payments/payment-router.js (X-PAYMENT-RAIL).
• Négociation dynamique de prix (Price Discovery) via POST /x402/negotiate (src/x402/price-negotiation.js), avec remise au volume et majoration selon la charge serveur.
• Circuit Breaker anti-fraude par client/IP (src/security/circuit-breaker.js).
• Isolation des secrets : variables d'environnement chiffrées AES-256-GCM ou HashiCorp Vault (src/vault/secrets-manager.js).
• Documentation internationale : README.es.md (Espagne/LATAM), README.en-IN.md (Inde, UPI/M2M).
• [Contributions Claude] Métriques Prometheus zéro-dépendance (src/metrics.js, /metrics), canal temps réel WebSocket (src/realtime/ws-notifier.js, /ws/events), traçage distribué léger compatible W3C Trace Context (src/tracing.js).

Toutes ces fonctionnalités sont désactivées par défaut (security.m2mAuth.enabled, security.circuitBreaker.enabled, payments.enabledRails, x402Negotiation.enabled, realtime.enabled dans config/config.json) pour rester rétrocompatibles avec les déploiements v1 existants. Voir config/config.example.json pour la configuration complète.

🚀 v3 — Prête pour l'échelle Google/Coinbase/AWS

La v3 ajoute les briques qui manquaient pour rivaliser avec l'infrastructure x402 actuelle (facilitator Coinbase CDP, x402 Foundation sous Linux Foundation) plutôt que de simplement la consommer.

Conformité protocolaire réelle

• EIP-3009 réel (transferWithAuthorization) pour USDC/EURC on-chain (src/x402-protocol/schemes/exact-evm.js)
• Permit2 pour accepter n'importe quel ERC-20 (src/x402-protocol/schemes/permit2.js)
• Registre multi-chaînes CAIP-2 : Base, Base Sepolia, Polygon, Arbitrum, Solana, Stellar (src/x402-protocol/chain-registry.js)
• Schéma "upto" (paiement variable selon consommation réelle) et schéma "deferred" (licences pré-négociées + règlement par lot, conforme à la proposition Cloudflare) : src/x402-protocol/schemes/
• Suite de conformité au schéma JSON officiel (src/x402-protocol/conformance/schema-validator.js)

Devenir un facilitator indépendant

• Endpoints /facilitator/verify, /facilitator/settle, /facilitator/supported (src/x402-protocol/facilitator.js) — réduit la dépendance de l'écosystème au facilitator centralisé Coinbase

Découverte & écosystème

• Manifeste /.well-known/x402-manifest.json, compatible Bazaar/Agent.market/x402scan (src/discovery/bazaar-manifest.js)
• Serveur MCP natif (src/mcp/mcp-server.js, node bin/cli.js mcp) — branchable directement dans Claude ou tout agent compatible MCP
• SDKs Python et Go (sdks/python/, sdks/go/), en plus du SDK Node existant

Conformité & sécurité niveau institution

• Screening KYT/OFAC pluggable (src/compliance/kyt-screening.js)
• Mode de conformité par juridiction (US-BSA, UE-MiCA, Inde-UPI/PSP) : src/compliance/jurisdiction-compliance.js
• Journal d'audit immuable ancré par Merkle (src/audit/merkle-ledger.js, endpoint /api/admin/audit/verify)
• SECURITY.md : politique de divulgation, checklist d'audit, limites connues assumées honnêtement

Scalabilité horizontale

• Store distribué Redis pour nonces M2M et rate limiting (src/scaling/redis-store.js), remplace les Map en mémoire qui ne survivent pas au multi-instance
• Oracle de prix on-chain (Pyth/Chainlink) remplaçant les taux statiques (src/oracle/price-oracle.js)

Toutes ces fonctionnalités restent désactivées par défaut (facilitator.enabled, compliance.kyt.type: "none", mcp.enabled...) pour rester rétrocompatibles. Voir config/config.example.json.

📡 Comment fonctionne le protocole x402

1. Le client appelle une route protégée, ex. /api/products
2. Le serveur répond 402 Payment Required avec le prix et les instructions
3. Le client génère une preuve de paiement et la renvoie
4. Le serveur vérifie, exécute le SQL (avec cache et pagination), renvoie les données

⚙️ Configuration complète (config/config.json)

{
  "server": { "port": 3000, "host": "localhost" },
  "database": { "type": "sqlite", "path": "./database/data.db", "autoCreate": true, "connectionString": "" },
  "wallet": { "address": "0x...", "mode": "simulation", "realAddress": "" },
  "freeMode": false,
  "developerMode": false,
  "paymentMode": "simulation",
  "cache": { "enabled": true, "ttlMs": 5000 },
  "rateLimit": { "enabled": true, "windowMs": 60000, "maxRequests": 60 },
  "webhooks": { "enabled": false, "urls": [] },
  "x402RealMode": { "network": "base-sepolia", "facilitatorUrl": "https://x402.org/facilitator" },
  "routes": [ { "path": "/api/users", "method": "GET", "price": "0.01", "sql": "SELECT * FROM users LIMIT 20" } ]
}

🛠️ Commandes disponibles

Commande	Description
npm start	Démarre le serveur
npm run test	Simule un agent IA qui paie
npm run test:unit	Lance les 14 tests unitaires
npm run monetize -- /chemin/base.db	Auto-génère les routes depuis une base existante
npm run generate-wallet	Génère un vrai wallet testnet
npm run reset-db	Réinitialise la base de démo
node scripts/pay-as-agent.js /api/users	Paiement réel testnet, clé lue depuis .env
docker compose up	Démarre tout via Docker
node bin/cli.js help	Aide de la CLI

📂 Structure du projet

SQLite-x402-Gateway/
├── src/
│   ├── index.js, server.js, gateway.js
│   ├── payment-simulator.js, real-x402-adapter.js
│   ├── schema-introspector.js ⭐
│   ├── db-adapters/ (sqlite, postgres, mysql, mongodb, db-interface.js)
│   ├── security/ (hmac-auth.js, circuit-breaker.js, whitelist-validator.js)
│   ├── payments/ (stripe-adapter.js, lightning-adapter.js, payment-router.js)
│   ├── pagination/ (keyset-pagination.js)
│   ├── x402/ (price-negotiation.js)
│   ├── x402-protocol/ (chain-registry.js, facilitator.js, schemes/, conformance/) — v3
│   ├── discovery/ (bazaar-manifest.js) — v3
│   ├── compliance/ (kyt-screening.js, jurisdiction-compliance.js) — v3
│   ├── audit/ (merkle-ledger.js) — v3
│   ├── oracle/ (price-oracle.js) — v3
│   ├── scaling/ (redis-store.js) — v3
│   ├── mcp/ (mcp-server.js) — v3
│   ├── vault/ (secrets-manager.js)
│   ├── realtime/ (ws-notifier.js) — contribution Claude
│   ├── metrics.js, tracing.js — contributions Claude
│   ├── cache.js, rate-limiter.js, webhooks.js, openapi-generator.js
│   ├── env-loader.js, config-loader.js, database-init.js, logger.js, admin.js
├── public/ (interface admin + graphique)
├── scripts/ (test-client, monetize, generate-wallet, pay-as-agent)
├── bin/cli.js (+ commande `mcp`)
├── packages/client/ (SDK Node.js)
├── sdks/python/, sdks/go/ (SDKs Python et Go) — v3
├── test/ (52 tests node:test)
├── config/, database/
├── Dockerfile, docker-compose.yml
├── .github/workflows/ci.yml
├── .env.example
├── README.md, README.es.md, README.en-IN.md, docs/README-EN.md
├── SECURITY.md — v3
├── LICENSE (MIT), CONTRIBUTING.md

⚠️ Limites connues (honnêteté avant tout)

• Le mode simulation est un outil pédagogique/MVP, pas une intégration blockchain de production.
• Le mode réel utilise le testnet Base Sepolia par défaut ; passer à "base" (mainnet) implique de vrais fonds.
• Le schéma "upto" n'est simulé que côté serveur ; aucune implémentation on-chain officielle disponible à ce jour dans x402-express.
• Le support PostgreSQL suppose que vos requêtes de config sont compatibles (SELECT + LIMIT/OFFSET standards).

📄 Licence

MIT — voir LICENSE

🤝 Contribuer

Voir CONTRIBUTING.md