anchorage_layer_simple/api-relay/docs/synthese.md

Synthèse – API Relay (UserWallet)

Author: Équipe 4NK
Date: 2026-01-26

1. Rôle

Relais de stockage et de diffusion pour le login décentralisé UserWallet : messages chiffrés, signatures et clés publiés séparément, adressés par hash, récupération par GET (pull). Pas de destinataire explicite ; déduplication par hash.

2. Stack

• Runtime : Node.js, ESM ("type": "module").
• Serveur : Express, http.createServer, timeout configurable.
• Build : TypeScript, module/moduleResolution Node16, imports .js. npm start → node dist/index.js.
• Middleware : CORS (origines via CORS_ORIGINS), Pino (logging HTTP), compression gzip, express-rate-limit, express.json (body limit).
• Validation : lib/validate (MsgChiffre, MsgSignature, MsgCle) ; 400 si corps invalide.
• Métriques : Prometheus (prom-client), GET /metrics.

3. Structure

src/
  index.ts          # Bootstrap, storage, relay, routes, server timeout
  lib/
    logger.ts       # Pino
    validate.ts     # validateMsgChiffre, validateMsgSignature, validateMsgCle
  middleware/
    index.ts        # CORS, logging, compression, rate limit ; getBodyLimit, getRequestTimeoutMs
  routes/
    health.ts       # GET /health
    messages.ts     # GET/POST /messages, GET /messages/:hash
    signatures.ts   # GET /signatures/:hash, POST /signatures
    keys.ts         # GET /keys/:hash, POST /keys
    metrics.ts      # GET /metrics
    bloom.ts        # GET /bloom
  services/
    storage.ts      # StorageService (messages, signatures, keys, seenHashes, byService)
    relay.ts        # RelayService (relayMessage, relaySignature, relayKey)
  types/
    message.ts      # MsgChiffre, MsgSignature, MsgCle, Stored*

4. Endpoints

Méthode	Chemin	Description
GET	/health	{ status: 'ok', timestamp }
GET	/messages?start=&end=&service=	Messages dans la fenêtre ; service optionnel (index byService).
POST	/messages	Enregistrement + relais si hash non vu.
GET	/messages/:hash	Message par hash.
GET	/signatures/:hash	Signatures pour un message.
POST	/signatures	Enregistrement + relais.
GET	/keys/:hash	Clés de déchiffrement pour un message.
POST	/keys	Enregistrement + relais.
GET	/metrics	Métriques Prometheus (relay_storage_entries{kind}).
GET	/bloom	Bloom filter (JSON) des hash vus.

5. Configuration (env)

• PORT, HOST : écoute (défaut 3019, 0.0.0.0).
• STORAGE_PATH : répertoire de persistance (défaut ./data).
• PEER_RELAYS : relais pairs (virgule), ex. http://relay1:3019,http://relay2:3019.
• SAVE_INTERVAL_SECONDS : sauvegarde périodique (défaut 300 ; 0 = désactivé).
• BODY_LIMIT, REQUEST_TIMEOUT_MS : body JSON max, timeout HTTP.
• RATE_LIMIT_WINDOW_MS, RATE_LIMIT_MAX : fenêtre et max requêtes par IP.
• CORS_ORIGINS : origines autorisées (virgule) ; vide = toutes.
• LOG_LEVEL, NODE_ENV : Pino et environnement.

6. Stockage

• Mémoire : messages, signatures, keys, seenHashes, index byService.
• Disque : {STORAGE_PATH}/messages.json (messages, seenHashes, signatures, keys). Chargement au démarrage ; sauvegarde à l’arrêt (SIGINT/SIGTERM) et périodique si SAVE_INTERVAL_SECONDS > 0.
• Limitations : pas de base SQLite/PostgreSQL ; en production, une base dédiée est recommandée.

7. Déploiement

• Dev : npm run dev (tsx watch).
• Build : npm run build puis npm start ou ./start.sh.
• Systemd : api-relay.service ; WorkingDirectory = repo, ExecStart = ./start.sh. Voir README.

8. Liens avec UserWallet

• UserWallet appelle les endpoints (messages, signatures, keys, health) via utils/relay.
• Types alignés : MsgChiffre, MsgSignature, MsgCle (datajson_public, etc.).
• Port par défaut 3019 ; front 3018. Proxy Nginx : voir features/nginx-proxy-relay-certificator.md.

9. Références

• README : api-relay/README.md.
• Évolutions : features/api-relay-evolutions.md.
• Persistance : features/api-relay-persistence-signatures-keys-periodic-save.md.