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