ENI-projet-piscine/docs/adr/0007-terminaison-tls-et-reverse-proxy-nginx.md

0007 - Terminaison TLS par un reverse proxy Nginx, en Docker Compose

• Statut : accepté
• Date : 2026-09-21

Contexte

Quatre documents désignaient le même trou. 10-infra.md ouvrait ses questions par « Quel ingress remplace Traefik, et qui termine le TLS ». 00-vue-ensemble.md rangeait « TLS, HSTS et CSP » dans « Absent, et assumé ». owasp-traceabilite.md laissait la ligne API8 transport ouverte. 31-contrat-authentification.md listait deux corrections « à faire avant la démonstration » : servir le SPA et l'API sous la même origine, et servir en HTTPS.

Ce n'est pas un durcissement facultatif, c'est une condition de fonctionnement. Les deux fichiers apps/frontend/src/environments/environment*.ts portent apiUrl: '/api/v1', en relatif. En développement, proxy.conf.json route /api vers l'API. Une fois en conteneur, plus rien ne le fait : l'application déployée ne peut pas appeler son API. Et le cookie de rafraîchissement prend le préfixe __Secure- dès que APP_ENV sort de local, donc sans HTTPS il n'est jamais posé et l'authentification ne tient pas au rechargement de page.

La contrainte qui cadre tout le reste : aucun nom de domaine public n'existe. La cible documentée est le serveur on-premise de l'école, ssh_host = "10.0.0.10" dans le terraform.tfvars.example. Sur une adresse privée, le défi HTTP-01 de Let's Encrypt ne peut pas aboutir, faute de DNS public et de port 80 entrant.

Décision

Un service proxy dans Docker Compose, image officielle nginx:1.28-alpine, seul composant à publier des ports sur la machine : 80 et 443. Backend et frontend ne sont plus publiés du tout, la base et l'interface Mailpit sont ramenées sur la boucle locale. La stack complète est décrite par l'overlay docker-compose.prod.yml, le docker-compose.yml restant la boucle de développement.

Le SPA et l'API sont servis sous la même origine : / vers le conteneur frontend, /api/ vers l'API en préservant le préfixe /api/v1. Le CORS cesse d'être un mécanisme de production et redevient ce qu'il est, un filet pour les appels croisés qui ne devraient plus exister.

nginx lit toujours les deux mêmes fichiers, /etc/nginx/tls/fullchain.pem et privkey.pem. Seule leur fabrication varie : un script openssl pour la démonstration, le --deploy-hook de certbot quand un domaine existera. La configuration nginx ne connaît pas la différence et n'aura pas à changer le jour de la bascule.

Le proxy pose HSTS et CSP, que l'application refuse de poser. Ce refus est verrouillé par tests/api/test_hardening.py::test_the_application_never_sets_hsts_itself : l'application ne peut pas savoir si elle est jointe en HTTPS, le terminateur, si.

Pourquoi Compose et pas l'ingress k3s

Le module infra/terraform/modules/k3s/ installe un cluster et rien d'autre. Il ne déclare que le provider null, aucun namespace, aucun déploiement, aucun service, aucun ingress, et il n'a jamais été appliqué. Passer par un ingress supposait d'abord de combler tout ce qui manque entre les deux topologies : un registre d'images alimenté, des manifestes pour le front, l'API et la base, un stockage persistant pour PostgreSQL. C'est le chantier que 10-infra.md nomme « le trou entre les deux topologies », et il ne tient pas dans le jalon.

Compose, lui, fait déjà tourner les quatre services sur un réseau commun. Le proxy y entre comme un cinquième service, sans rien déplacer. La décision de désactiver Traefik reste valable : le choix d'ingress n'est pas tranché ici, il est repoussé avec le reste de la bascule Kubernetes.

Ce que le proxy n'expose pas, et pourquoi c'est structurel

/docs, /redoc, /openapi.json, /static et /metrics sont montés par l'API à la racine, pas sous le préfixe /api. Avec un routage où seul /api/ part vers l'API, ils tombent dans location /, donc sur le SPA, donc hors d'atteinte publique. Aucune règle de blocage n'est nécessaire, et il n'y en a pas : le jour où quelqu'un routera la racine vers l'API pour « réparer » Swagger, il publiera les métriques avec.

Conséquences

• APP_ENV, APP_DEBUG, APP_CORS_ORIGINS, APP_TRUST_PROXY_HEADERS et le TLS changent ensemble, dans le même fichier. Hors local, la configuration refuse de démarrer sans origine CORS, et le cookie devient __Secure-ev_refresh.
• APP_TRUST_PROXY_HEADERS passe à vrai, et le proxy écrit X-Forwarded-For avec $proxy_add_x_forwarded_for, qui ajoute l'IP réelle en fin de chaîne. C'est exactement ce que lit get_client_ip(). Toute autre forme ferait compter la limitation de débit par IP sur l'IP du proxy, c'est-à-dire globalement.
• --forwarded-allow-ips=* reste sans conséquence : uvicorn s'en sert pour réécrire request.client depuis X-Forwarded-For, et get_client_ip() est le seul lecteur de request.client du backend, en dernier recours quand l'en-tête est absent.
• Une limitation de débit au frontal existe désormais, distincte de celle de l'application : 20 requêtes par seconde sur l'API, et 30 par minute sur les seules routes qui vérifient un secret, login, password, forgot-password et reset-password. /auth/me et /auth/refresh en sont exclues : elles partent à chaque chargement de page, et le NAT de l'école donnant une seule adresse à toute la promotion, la zone resserrée les aurait transformées en 429 en démonstration.
• La CSP contraint le build du frontend. script-src 'self' interdit les gestionnaires d'événements en ligne, et l'inlining du CSS critique d'Angular produisait exactement cela : <link rel="stylesheet" media="print" onload="this.media='all'">. La feuille serait restée en media="print", donc l'application entière sans style. D'où styles.inlineCritical: false dans angular.json. style-src garde 'unsafe-inline', dont Angular a besoin pour les styles de composants injectés à l'exécution.
• La redirection 80 vers 443 conserve $host. Un client qui forge son en-tête Host obtient donc une redirection vers l'hôte de son choix. Risque accepté : un navigateur ne peut pas être amené à envoyer un Host étranger, aucun cache ne s'intercale, et figer un nom canonique couperait l'accès par adresse IP, seule voie ouverte sur 10.0.0.10.
• Aucun :? dans l'overlay. Compose interpole tout le fichier avant n'importe quelle sous-commande : une garde y casserait stop et logs autant que up. PUBLIC_HOST retombe donc sur enervision.local, et make stack-up vérifie à la place que le certificat présent couvre l'hôte demandé, ce qui est la condition réelle à tenir.
• Le proxy attend une API saine et pas seulement démarrée : le HEALTHCHECK de l'image du backend sert de condition à depends_on, faute de quoi les premiers appels à /api/ répondent 502.
• La ligne API8 transport de owasp-traceabilite.md se referme.
• Let's Encrypt n'est pas prouvé. Le chemin ACME est livré, monté et documenté ; il n'a pas été exercé faute de domaine. Le certificat de démonstration est auto-signé, le navigateur avertit, et c'est la situation réelle du projet, pas un raccourci.
• Le proxy résout ses cibles par le résolveur interne de Docker plutôt que par un bloc upstream, sans quoi recréer le seul conteneur backend suffirait à produire des 502 jusqu'au rechargement.

Alternatives écartées

• Ingress k3s avec cert-manager : la bonne cible, et elle reste la cible. Elle suppose un registre et des manifestes qui n'existent pas, à quatre jours du rendu.
• Étendre le nginx.conf du conteneur frontend avec un location /api et l'écoute TLS : moins de pièces, mais les certificats entrent dans l'image du front et tout rebuild du front redéploie le terminateur TLS. La séparation des cycles de vie vaut le conteneur supplémentaire.
• Traefik ou Caddy, qui automatisent ACME : ils déplacent le problème sans le résoudre, le défi HTTP-01 échouant pour la même raison. Et l'issue nomme Nginx.
• Let's Encrypt par défi DNS-01 : fonctionne derrière une IP privée, mais exige un domaine possédé et un jeton d'API chez le fournisseur DNS. Rouvrable sans rien changer à la configuration nginx le jour où ces deux éléments existent.
• Un Dockerfile de proxy : inutile, la configuration est montée en volume. Cela évite aussi la dépendance à un registre authentifié, piège déjà présent dans apps/frontend/Dockerfile.