The codeSécurité(in French)7 min read
Webhooks et échanges
Les appels de machine à machine (Stripe, la tâche planifiée, le site vers l’ERP et l’ERP vers le site), comment chacun prouve qui l’envoie, ce qu’un message rejoué peut faire, et ce qui se passe quand l’appel échoue.
Not translated yet
Certains appels arrivent sans session : les événements de Stripe, la veille planifiée chaque matin, les événements et les demandes de PDF du site vers l’ERP, l’invalidation du cache de l’ERP vers le site. La liste des canaux et leur contrat sont décrits dans Échanges entre les applications, et le traitement d’un paiement dans Stripe. Ici, je décris ce qui les protège.
| Appel | Ce qui prouve l’expéditeur | Contre le rejeu | En cas d’échec |
|---|---|---|---|
Stripe → ERP, /api/webhooks/stripe | signature Stripe, vérifiée sur les octets bruts | horodatage signé, événement inscrit par son identifiant | réponse en erreur, Stripe relivre plus tard |
Tâche planifiée → ERP, /api/veille | jeton porteur | des étapes qui ne traitent que ce qui est arrivé à échéance | une sonde externe alerte si le battement manque |
| Site → ERP, événements | HMAC-SHA256 de l’horodatage et du corps | fenêtre de cinq minutes, et pour une rétractation, une commande qui doit avoir changé récemment | journalisé, avec une alerte pour une suppression de compte |
| Site → ERP, PDF d’un devis ou d’une facture | jeton porteur | lecture seule, droit revérifié à chaque pièce | le client voit le document indisponible |
| ERP → site, invalidation du cache | jeton porteur | sans effet sur les données : invalider deux fois ne change rien | le cache expire à son terme |
Prouver l’expéditeur
Une route machine est publique : n’importe qui peut lui envoyer une requête. Sans preuve, un faux événement de paiement marquerait une commande payée, et un faux événement du site inscrirait un effacement.
- Chaque usage a son secret : Stripe, la veille, le cache, les événements, les documents. Si un secret fuit, il n’ouvre que son geste. Celui des événements, qui inscrit au registre des effacements, n’est pas celui qui ouvre les PDF. Les secrets de cookie sont différents aussi d’une application à l’autre. Avec la même valeur, un cookie scellé par le site passerait la garde du proxy de l’ERP.
- La signature est vérifiée avant toute lecture. Le webhook Stripe et les événements du site sont signés sur leur corps exact. La route lit les octets bruts, vérifie, et seulement après elle analyse le JSON (
webhook-raw-body.regression.test.ts). Un corps réécrit, même d’un espace, est refusé. - Les jetons porteurs se comparent à temps constant, par
safeEquals(packages/infra/src/safe-equals.ts), qui compare les empreintes des deux valeurs. Du coup, ni le temps de réponse ni la longueur ne donnent d’indice sur le secret. - Chaque route a une garde nommée. Les routes machine échappent au proxy de session, mais pas à la garde. Un test associe chaque gestionnaire de route à la vérification qu’il doit appeler. Il la cherche dans ce que la route appelle vraiment, et un import ou un commentaire ne lui suffit pas (
photo-upload-route.regression.test.ts). - Sans son secret, une route reste fermée et refuse tout appel (
SITE_REFUSAL_STATUS,runMonitoring). Et un déploiement refuse de démarrer sans les secrets de ses canaux (schémas d’environnement des deux applications).
Ça se vérifie dans apps/erp/shared/server/site-request.ts et packages/contracts/src/site-events.ts, avec leurs tests, et dans stripe-webhook.service.ts pour Stripe.
Limiter le rejeu
Un message authentique, capturé puis renvoyé, refait son effet, et il n’y a pas besoin d’en connaître le secret.
- Stripe signe un horodatage avec le corps, et le SDK refuse une livraison trop ancienne. L’ERP inscrit chaque événement par son identifiant avant de le traiter (
WebhookEvent). Un doublon déjà traité répond donc tout de suite, sans rien refaire. - Les événements du site portent leur horodatage dans la signature. L’ERP le vérifie avant même de lire le corps, et au-delà de cinq minutes d’écart, il refuse l’événement (
SITE_EVENT_TOLERANCE_SECONDS). En plus, pour une rétractation, l’ERP n’agit que si la commande vient de changer (SITE_EVENT_FRESHNESS_MS). Une rétractation rejouée une heure plus tard ne prévient donc plus personne. Une suppression de compte, elle, n’a que la signature et la fenêtre : l’ERP inscrit l’empreinte qu’elle porte. - Les autres canaux n’ont pas d’effet qui s’accumule. Une invalidation de cache ou une lecture de PDF rejouée ne fait que se refaire, et les étapes de la veille ne traitent que ce qui est arrivé à échéance.
Pour les doublons, c’est vérifié par stripe-webhook.service.test.ts et dispute-webhook.db.test.ts. Pour la fenêtre et la fraîcheur, c’est site-request.test.ts et site-event-gate.test.ts (apps/erp/shared/server/__tests__).
Ne croire que le nécessaire
Un message authentique peut contenir une donnée fausse : un montant modifié avant le paiement, un identifiant qui n’est pas le bon, un événement du mauvais environnement.
- Un événement du site ne contient que sa sorte et un identifiant, de forme stricte (
siteEventSchema). Pour une rétractation, l’ERP relit tout le reste dans sa base. Pour une suppression de compte, l’identifiant est l’empreinte de l’adresse, et c’est elle qu’il inscrit au registre. - Un paiement n’est accepté que s’il correspond à sa commande. L’identifiant, le montant et la devise de la session Stripe doivent être ceux de la commande (
reconcileSession,webhook-session.service.ts). S’ils ne correspondent pas, la commande est fermée sans être marquée payée, et une alerte part pour qu’on rembourse. - Un événement Stripe d’un autre mode que la clé (test reçu par la prod, ou l’inverse) est ignoré et signalé.
- Une facture demandée par le site n’est rendue que si elle appartient à une commande payée du compte connecté, et si son archive a l’empreinte attendue (
site-invoice-pdf.service.ts). - Le site n’invalide que des tags qu’il connaît (
isRevalidableTag), et seul l’ERP de prod l’appelle. Une preview ne vide donc jamais le cache public. - Les corps de chaque canal sont validés par les schémas de
packages/contracts. Pour le cache et les événements, l’émetteur vérifie aussi le sien à la compilation avecsatisfies. Les deux demandes de PDF passent parrequestErpPdf, qui prend un objet sans type (Échanges).
C’est vérifié par stripe-webhook.service.test.ts pour le mode et les rapprochements, par site-invoice-pdf.service.test.ts pour les factures, et par apps/site/app/api/revalidate/__tests__ et site-revalidation.ts (prod seule) pour l’invalidation du cache.
Quand un appel échoue
Côté Stripe, un échec passager répond par une erreur, et Stripe relivre plus tard. L’inscription écarte un doublon déjà traité. Et les écritures conditionnelles de chaque traitement empêchent un événement interrompu puis rejoué de compter deux fois (Un ordre dont on ne sait pas s’il est parti). Une signature refusée sur une livraison de forme réelle déclenche une alerte, au plus une par quart d’heure, parce qu’elle révèle un secret désaccordé. Une livraison validée par l’ancien secret pendant une rotation alerte aussi, pour qu’on termine la rotation.
Du site vers l’ERP, un événement part une fois, avec un délai limité, sans suivre de redirection (redirect: "error"). Le secret et le corps ne partent donc vers aucune autre adresse que celle de l’ERP. Si une suppression de compte n’a pas pu être inscrite au registre des effacements, une alerte part, avec la marche à suivre avant toute restauration (apps/site/shared/server/site-events.ts).
La veille signale chaque passage réussi à une sonde externe, qui prévient si le heartbeat n’arrive pas (ERP).
Les compromis
- Il n’y a pas de file d’attente entre les applications. Un événement du site part une fois. Une rétractation perdue est journalisée, et une suppression de compte perdue déclenche une alerte. Une file durable garantirait la livraison. Mais ce serait un service de plus à héberger et à surveiller pour deux sortes d’événements.
- L’invalidation du cache, la veille et les PDF sont protégés par un jeton porteur, sans signature horodatée. Un en-tête capturé pourrait donc se rejouer jusqu’au changement du secret. L’invalidation et les PDF ne modifient aucune donnée. La veille, elle, écrit (elle applique les durées de conservation et envoie les alertes). Mais chaque étape ne traite que ce qui est arrivé à échéance, donc la rejouer ne refait rien. Ces canaux passent par HTTPS imposé (HSTS), et l’ERP revérifie le droit à chaque document.
- Les devis et les factures se demandent avec le même secret. C’est le même appelant et le même genre de geste, et l’ERP revérifie chaque pièce.
- Seuls certains secrets se changent en deux temps. Le webhook Stripe accepte l’ancien secret pendant une rotation. Les secrets des canaux entre applications se changent dans les deux projets en même temps, et les refus pendant le changement se voient dans les journaux. Celui de la veille n’est que dans le projet de l’ERP, et il se change d’un coup.