@zevra/support 0.2.0

package/src/relais/corps.ts

@@ -0,0 +1,292 @@
+// ============================================================================
+// Ce que le navigateur a le droit de dire — et ce qu'on lui impose. PUR.
+// ============================================================================
+//
+// ⚠️ LA RÈGLE, EN UNE PHRASE : **l'identité du requérant vient de la session
+// de l'app hôte, jamais du corps reçu.**
+//
+// Sans elle, le formulaire « Aide » devient un moyen d'écrire une demande au
+// nom de n'importe qui (il suffit de changer l'adresse dans l'onglet Réseau),
+// puis — puisque `GET /demandes?email=` liste par adresse — de LIRE le fil de
+// cette personne, contexte technique compris. Ce n'est pas une faille exotique
+// : c'est le comportement par défaut de tout relais écrit avec un
+// `JSON.parse(await req.text())` transmis tel quel.
+//
+// D'où la forme de ce fichier : une liste blanche de champs, et l'identité
+// recollée par-dessus, en dernier.
+
+import type {
+  ContexteDemande,
+  EntreeAjouterMessage,
+  EntreeCreerDemande,
+  EntreeDeposerPiece,
+  EntreeListerDemandes,
+  Requerant,
+  StatutDemande,
+  TypeDemande,
+} from '../types'
+import { TYPES_DEMANDE } from '../types'
+
+/** Qui parle, selon l'app hôte. C'est la SEULE source d'identité du relais. */
+export interface IdentiteRequerant {
+  email: string
+  nom?: string | null
+  idExterne?: string | null
+}
+
+/** Les champs qu'un navigateur peut poser sur une création. Rien d'autre. */
+export const CHAMPS_CREATION_ACCEPTES = [
+  'type',
+  'titre',
+  'description',
+  'contexte',
+  'pieces',
+  'campagne_id',
+  'scenario',
+  'score',
+] as const
+
+/** Au-delà, ce n'est plus un contexte, c'est un vidage de mémoire. */
+export const MAX_ERREURS_CONSOLE = 20
+export const LONGUEUR_CHAMP_CONTEXTE = 500
+export const LONGUEUR_TITRE = 200
+
+/**
+ * Normalise une adresse comme le fait Support (`domaine/validation.ts`).
+ *
+ * Recopié sciemment : le paquet ne dépend pas de l'app. Idempotent.
+ */
+export function normaliserEmail(brut: unknown): string {
+  return typeof brut === 'string' ? brut.trim().toLowerCase() : ''
+}
+
+/**
+ * Compose le corps de `POST /demandes` à partir de ce que le navigateur a
+ * envoyé et de qui l'app dit que c'est. PUR.
+ *
+ * ⚠️ L'ordre compte : on RECOPIE les champs autorisés, puis on POSE
+ * `requerant`. Un `{ ...recu, requerant: identite }` aurait le même effet ici,
+ * mais laisserait passer tout le reste du corps (`app_id`, `statut`,
+ * `priorite`, `assignee_id`…) le jour où l'API v1 accepterait un champ de
+ * plus. La liste blanche ne se périme pas dans ce sens-là.
+ */
+export function composerCreation(
+  recu: unknown,
+  identite: IdentiteRequerant,
+): EntreeCreerDemande {
+  const brut = objetOuVide(recu)
+
+  const requerant: Requerant = {
+    email: normaliserEmail(identite.email),
+    nom: texteOuNull(identite.nom),
+    id_externe: texteOuNull(identite.idExterne),
+  }
+
+  return {
+    // ⚠️ ABSENTS, ILS RESTENT ABSENTS (`null`). Une demande en une phrase
+    // n'a ni type ni titre, et c'est Support qui les fait poser par le triage
+    // IA. Les remplacer ici par une valeur par défaut les ferait passer pour
+    // un CHOIX du requérant, que l'IA n'aurait plus le droit de corriger.
+    type: typeOuNull(brut.type),
+    titre: titreOuNull(brut.titre),
+    description: texteOuVide(brut.description),
+    requerant,
+    contexte: bornerContexte(brut.contexte),
+    pieces: listeIdentifiants(brut.pieces),
+    campagne_id: texteOuNull(brut.campagne_id),
+    scenario: texteOuNull(brut.scenario),
+    score: scoreOuNull(brut.score),
+  }
+}
+
+/**
+ * Compose les critères de `GET /demandes`. PUR.
+ *
+ * ⚠️ L'`email` de la query string reçue est IGNORÉ, pas recopié : c'est le
+ * paramètre par lequel on lirait le fil d'autrui. Le statut, lui, ne dit rien
+ * de personne et peut venir du navigateur — après contrôle.
+ */
+export function composerListe(
+  requete: URLSearchParams | undefined,
+  identite: IdentiteRequerant,
+): EntreeListerDemandes {
+  const statuts = (requete?.getAll('statut') ?? []).filter(estStatut)
+  const limiteBrute = Number(requete?.get('limite') ?? '')
+  return {
+    email: normaliserEmail(identite.email),
+    statut: statuts.length > 0 ? statuts : undefined,
+    limite: Number.isInteger(limiteBrute) && limiteBrute > 0 ? limiteBrute : undefined,
+    curseur: requete?.get('curseur') || undefined,
+  }
+}
+
+/** Compose `POST /demandes/:id/messages`. L'adresse vient de l'identité. PUR. */
+export function composerMessage(
+  recu: unknown,
+  identite: IdentiteRequerant,
+): EntreeAjouterMessage {
+  const brut = objetOuVide(recu)
+  return {
+    corps: texteOuVide(brut.corps),
+    requerant_email: normaliserEmail(identite.email),
+    pieces: listeIdentifiants(brut.pieces),
+  }
+}
+
+/** Compose `POST /pieces`. Ici il n'y a pas d'identité à imposer. PUR. */
+export function composerDepotPiece(recu: unknown): EntreeDeposerPiece {
+  const brut = objetOuVide(recu)
+  const octets = Number(brut.octets)
+  return {
+    nom: borner(texteOuVide(brut.nom), 200),
+    type_mime: borner(texteOuVide(brut.type_mime), 100),
+    octets: Number.isFinite(octets) && octets > 0 ? Math.floor(octets) : 0,
+  }
+}
+
+/**
+ * Cette demande est-elle bien celle de cette personne ? PUR.
+ *
+ * ⚠️ `GET /api/v1/demandes/:id` rend n'importe quelle demande DE L'APP : la
+ * clé suffit, l'adresse n'y entre pas. Le relais, lui, parle au nom d'un
+ * visiteur — il doit donc refaire la vérification, sinon un identifiant
+ * recopié d'un collègue ouvre son fil.
+ *
+ * Les trois cas se distinguent :
+ *   - adresses égales (à la casse près)    → `true`
+ *   - adresses différentes                  → `false`
+ *   - une des deux manque                   → `false` AUSSI, et c'est le point :
+ *     « on ne sait pas » ne doit pas valoir « d'accord ». Une demande sans
+ *     adresse de requérant (import, migration, cas non prévu) ne s'ouvre à
+ *     personne par défaut.
+ */
+export function verifierAppartenance(
+  emailDemande: unknown,
+  emailIdentite: unknown,
+): boolean {
+  const a = normaliserEmail(emailDemande)
+  const b = normaliserEmail(emailIdentite)
+  if (a === '' || b === '') return false
+  return a === b
+}
+
+/* ─── Nettoyage du contexte ─────────────────────────────────────────── */
+
+/**
+ * Borne le contexte relevé par le widget. PUR.
+ *
+ * Le contexte est le seul champ que le navigateur remplit tout seul, donc le
+ * seul dont personne ne surveille la taille : 20 erreurs de console d'une app
+ * bavarde suffisent à dépasser les 256 Ko du corps. On borne ici, côté
+ * serveur, parce qu'un widget d'une version antérieure ne bornera pas.
+ */
+export function bornerContexte(recu: unknown): ContexteDemande | null {
+  if (typeof recu !== 'object' || recu === null) return null
+  const brut = recu as Record<string, unknown>
+  const contexte: ContexteDemande = {}
+
+  const texte = (valeur: unknown) => {
+    const t = texteOuVide(valeur)
+    return t === '' ? undefined : borner(t, LONGUEUR_CHAMP_CONTEXTE)
+  }
+
+  contexte.url = texte(brut.url)
+  contexte.user_agent = texte(brut.user_agent)
+  contexte.version = texte(brut.version)
+  contexte.os = texte(brut.os)
+  contexte.viewport = texte(brut.viewport)
+  contexte.langue = texte(brut.langue)
+
+  if (Array.isArray(brut.console)) {
+    const lignes = brut.console
+      .slice(-MAX_ERREURS_CONSOLE)
+      .map((ligne) => borner(texteOuVide(ligne), LONGUEUR_CHAMP_CONTEXTE))
+      .filter((ligne) => ligne !== '')
+    if (lignes.length > 0) contexte.console = lignes
+  }
+
+  if (typeof brut.extra === 'object' && brut.extra !== null && !Array.isArray(brut.extra)) {
+    // `extra` est libre par contrat : on le garde tel quel, mais seulement
+    // s'il se sérialise. Un objet circulaire ferait jeter `JSON.stringify` au
+    // moment de l'envoi — c'est-à-dire loin d'ici, dans un message
+    // incompréhensible.
+    try {
+      const rendu = JSON.stringify(brut.extra)
+      if (rendu !== undefined && rendu.length <= 4000) {
+        contexte.extra = JSON.parse(rendu) as Record<string, unknown>
+      }
+    } catch {
+      // Un extra illisible n'est pas une raison de perdre le reste du contexte.
+    }
+  }
+
+  for (const cle of Object.keys(contexte) as (keyof ContexteDemande)[]) {
+    if (contexte[cle] === undefined) delete contexte[cle]
+  }
+  return Object.keys(contexte).length === 0 ? null : contexte
+}
+
+/* ─── Petites conversions ───────────────────────────────────────────── */
+
+function objetOuVide(valeur: unknown): Record<string, unknown> {
+  return typeof valeur === 'object' && valeur !== null && !Array.isArray(valeur)
+    ? (valeur as Record<string, unknown>)
+    : {}
+}
+
+function texteOuVide(valeur: unknown): string {
+  return typeof valeur === 'string' ? valeur.trim() : ''
+}
+
+function texteOuNull(valeur: unknown): string | null {
+  const texte = texteOuVide(valeur)
+  return texte === '' ? null : texte
+}
+
+function borner(texte: string, longueur: number): string {
+  return texte.length <= longueur ? texte : `${texte.slice(0, longueur - 1)}…`
+}
+
+/**
+ * Un type hors vocabulaire retombe sur `question`, jamais sur `bug`.
+ *
+ * Un faux bug déclenche des priorités et des alertes ; une fausse question
+ * attend son tour. En cas de doute, on choisit le geste réversible.
+ */
+function typeOuNull(valeur: unknown): TypeDemande | null {
+  return typeof valeur === 'string' && (TYPES_DEMANDE as readonly string[]).includes(valeur)
+    ? (valeur as TypeDemande)
+    : null
+}
+
+function titreOuNull(valeur: unknown): string | null {
+  const titre = texteOuVide(valeur).trim()
+  return titre === '' ? null : borner(titre, LONGUEUR_TITRE)
+}
+
+const STATUTS: readonly string[] = [
+  'nouvelle',
+  'ouverte',
+  'en_attente_requerant',
+  'resolue',
+  'fermee',
+]
+
+function estStatut(valeur: string): valeur is StatutDemande {
+  return STATUTS.includes(valeur)
+}
+
+function listeIdentifiants(valeur: unknown): string[] | undefined {
+  if (!Array.isArray(valeur)) return undefined
+  const ids = valeur.filter(
+    (v): v is string => typeof v === 'string' && /^[0-9a-z-]{1,64}$/i.test(v),
+  )
+  return ids.length > 0 ? ids.slice(0, 10) : undefined
+}
+
+function scoreOuNull(valeur: unknown): number | null {
+  const n = Number(valeur)
+  if (!Number.isFinite(n)) return null
+  const entier = Math.round(n)
+  return entier >= 1 && entier <= 5 ? entier : null
+}

package/src/relais/routes.ts

@@ -0,0 +1,380 @@
+// ============================================================================
+// `creerRoutesSupport()` — le relais qui détient la clé. IMPUR.
+// ============================================================================
+//
+// Une app cliente pose UN fichier :
+//
+//   // app/api/support/[...chemin]/route.ts
+//   import { creerRoutesSupport } from '@zevra/support'
+//   import { session } from '@/lib/auth'
+//
+//   export const { GET, POST } = creerRoutesSupport({
+//     identifier: async () => {
+//       const s = await session()
+//       return s ? { email: s.user.email, nom: s.user.name, idExterne: s.user.id } : null
+//     },
+//   })
+//
+// ⚠️ Ce fichier tourne au SERVEUR. C'est le seul endroit de l'app cliente où
+// la clé `sk_support_…` existe. Le widget, lui, n'appelle que `/api/support/*`
+// et ne connaît aucune clé : c'est toute l'architecture du lot, et c'est ce
+// qui rend l'erreur impossible plutôt que déconseillée.
+//
+// Les décisions vivent dans `chemins.ts` (quelles routes existent) et
+// `corps.ts` (quels champs sont acceptés, qui est le requérant). Ici, on ne
+// fait que les appliquer.
+
+import { creerClientSupport, type ClientSupport, type OptionsClientSupport } from '../client'
+import { ErreurSupport, estErreurSupport, MESSAGE_GENERIQUE } from '../erreurs'
+import type { DemandeCreee, DemandeLue } from '../types'
+import { resoudreRelais, type ActionRelais } from './chemins'
+import {
+  composerCreation,
+  composerDepotPiece,
+  composerListe,
+  composerMessage,
+  normaliserEmail,
+  verifierAppartenance,
+  type IdentiteRequerant,
+} from './corps'
+
+/** Ce que Next passe en second argument d'un gestionnaire attrape-tout. */
+export interface ContexteRoute {
+  params: { chemin?: string[] } | Promise<{ chemin?: string[] }>
+}
+
+export type GestionnaireRoute = (
+  requete: Request,
+  contexte: ContexteRoute,
+) => Promise<Response>
+
+export interface OptionsRoutesSupport extends OptionsClientSupport {
+  /**
+   * Qui est en train de parler, selon VOTRE session. `null` ⇒ 401.
+   *
+   * ⚠️ C'est la pièce que vous seul pouvez écrire, et la seule qui compte.
+   * La faire lire dans le corps de la requête (« l'email est dans le
+   * formulaire ») redonne au navigateur le droit de se déclarer qui il veut.
+   *
+   * ⚠️ `email` doit porter une VRAIE adresse. Une chaîne vide ou faite
+   * d'espaces est traitée comme une absence d'identité (401) : la liste des
+   * demandes se fait par adresse, et une adresse vide ne dit pas « personne »,
+   * elle efface le filtre — l'API rendrait toutes les demandes de l'app.
+   */
+  identifier: (requete: Request) => Promise<IdentiteRequerant | null> | IdentiteRequerant | null
+  /** Client déjà construit (tests, client partagé). Sinon il en crée un. */
+  client?: ClientSupport
+  /**
+   * Rendre `url_portail` au navigateur à la création. Défaut : NON.
+   *
+   * ⚠️ C'est un lien magique : qui l'a lit le fil sans se connecter. Le
+   * navigateur n'en a pas besoin (il a l'onglet « Mes demandes »), et le
+   * laisser passer le ferait atterrir dans l'historique, dans les journaux du
+   * proxy et dans tout outil de mesure branché sur les réponses réseau.
+   * À n'activer que si votre app affiche elle-même « suivre ma demande ».
+   */
+  revelerUrlPortail?: boolean
+  /**
+   * Branchez votre journal sur les échecs DU RELAIS. Reçoit le chemin et le
+   * statut rendu, jamais le corps de la demande.
+   *
+   * ⚠️ Nom distinct de `journaliser`, hérité de `OptionsClientSupport`, et ce
+   * n'est pas un doublon : il y a deux couches et deux journaux. `journaliser`
+   * voit les appels SORTANTS vers Support (tentatives, réessais, durées) ;
+   * `journaliserRelais` voit ce que le NAVIGATEUR a reçu. Une même panne s'y
+   * lit deux fois — un 429 côté sortant, un 429 côté entrant — et c'est cette
+   * paire qui dit si le réessai a servi.
+   */
+  journaliserRelais?: (evenement: {
+    chemin: string
+    statut: number
+    message?: string
+  }) => void
+}
+
+export interface RoutesSupport {
+  GET: GestionnaireRoute
+  POST: GestionnaireRoute
+}
+
+export function creerRoutesSupport(options: OptionsRoutesSupport): RoutesSupport {
+  // Créé une fois, à l'import du module de route : `creerClientSupport` ne
+  // jette pas quand la configuration manque (voir `configuration.ts`), donc
+  // une app non encore liée au Support démarre quand même — ses routes
+  // répondent 503 avec la phrase à corriger.
+  const client = options.client ?? creerClientSupport(options)
+
+  const gestionnaire: GestionnaireRoute = async (requete, contexte) => {
+    const params = await contexte?.params
+    const resolution = resoudreRelais(params?.chemin, requete.method)
+
+    if ('refus' in resolution) {
+      if (resolution.refus === 'methode_refusee') {
+        return reponseErreur(405, 'introuvable', 'Cette méthode ne vaut pas ici.', {
+          Allow: resolution.permises.join(', '),
+        })
+      }
+      // Même réponse pour « n'existe pas » et « existe mais pas pour vous » :
+      // un 403 distinct apprendrait au visiteur ce qu'il y a derrière.
+      return reponseErreur(404, 'introuvable', "Cette route du relais n'existe pas.")
+    }
+
+    if (!client.etat.pret) {
+      return reponseErreur(
+        503,
+        'interne',
+        `Le support n'est pas branché sur cette app. ${client.etat.problemes.join(' ')}`,
+      )
+    }
+
+    let identite: IdentiteRequerant | null
+    try {
+      identite = (await options.identifier(requete)) ?? null
+    } catch {
+      // Une session illisible n'est pas une identité : on refuse, on ne
+      // suppose pas. Le contraire ouvrirait le relais à chaque panne de la
+      // couche d'authentification de l'app hôte.
+      identite = null
+    }
+
+    // ⚠️ `normaliserEmail` ET PAS `!identite.email`, et la nuance n'est pas
+    // cosmétique : une adresse faite d'espaces passe le test de vérité de
+    // JavaScript. Elle traverse alors `composerListe`, devient `''`, et
+    // `serialiserQuery` OMET les valeurs vides — la requête part sans filtre
+    // d'adresse, et `GET /api/v1/demandes` rend TOUTES les demandes de l'app à
+    // ce navigateur. Une chaîne d'espaces dans une session est un cas de
+    // bordure, pas un cas de laboratoire (import, compte de service, champ
+    // rempli à la main) ; et rien ne le signalerait, la réponse étant une
+    // liste parfaitement valide.
+    const adresse = normaliserEmail(identite?.email)
+    if (!identite || adresse === '') {
+      return reponseErreur(
+        401,
+        'cle_invalide',
+        'Connectez-vous pour utiliser le support depuis cette app.',
+      )
+    }
+
+    try {
+      const donnees = await executer(resolution.action, resolution.demandeId, requete, identite, {
+        client,
+        revelerUrlPortail: options.revelerUrlPortail === true,
+      })
+      return reponseOk(donnees, resolution.action === 'creer_demande' ? 201 : 200)
+    } catch (erreur) {
+      const { statut, corps, entetes } = traduireErreur(erreur)
+      options.journaliserRelais?.({
+        chemin: (params?.chemin ?? []).join('/'),
+        statut,
+        // `detail` ne part JAMAIS vers le navigateur (voir `traduireErreur`) ;
+        // il n'existe que pour le journal, et c'est là qu'il doit atterrir.
+        message: estErreurSupport(erreur)
+          ? `${erreur.code}: ${erreur.message}${erreur.detail ? ` — ${erreur.detail}` : ''}`
+          : undefined,
+      })
+      return reponse(statut, corps, entetes)
+    }
+  }
+
+  return { GET: gestionnaire, POST: gestionnaire }
+}
+
+/* ─── L'aiguillage ──────────────────────────────────────────────────── */
+
+async function executer(
+  action: ActionRelais,
+  demandeId: string | undefined,
+  requete: Request,
+  identite: IdentiteRequerant,
+  contexte: { client: ClientSupport; revelerUrlPortail: boolean },
+): Promise<unknown> {
+  const { client } = contexte
+
+  if (action === 'creer_demande') {
+    const recu = await lireJson(requete)
+    const creee = await client.creerDemande(composerCreation(recu, identite))
+    return filtrerCreation(creee, contexte.revelerUrlPortail)
+  }
+
+  if (action === 'lister_demandes') {
+    const url = new URL(requete.url)
+    return client.listerDemandes(composerListe(url.searchParams, identite))
+  }
+
+  if (action === 'lire_demande') {
+    const lue = await client.lireDemande(demandeId as string)
+    exigerAppartenance(lue, identite)
+    return lue
+  }
+
+  if (action === 'ajouter_message') {
+    // Même garde que la lecture, et pour la même raison : sans elle, un
+    // identifiant recopié permet d'écrire dans le fil d'autrui — que le
+    // requérant recevra par mail, signé de son propre nom.
+    const lue = await client.lireDemande(demandeId as string)
+    exigerAppartenance(lue, identite)
+    const recu = await lireJson(requete)
+    return client.ajouterMessage(demandeId as string, composerMessage(recu, identite))
+  }
+
+  if (action === 'deposer_piece') {
+    const recu = await lireJson(requete)
+    // Le fichier lui-même ne passe PAS par ici : l'URL présignée rendue part
+    // directement vers S3 depuis le navigateur. Relayer 20 Mo ferait tenir la
+    // mémoire du serveur de l'app hôte pour un fichier qui ne l'intéresse pas.
+    return client.demanderDepotPiece(composerDepotPiece(recu))
+  }
+
+  return client.programmeActif()
+}
+
+/**
+ * Retire `url_portail` sauf demande explicite. PUR.
+ *
+ * Exporté pour être testé : c'est une décision, pas un détail de plomberie.
+ */
+export function filtrerCreation(creee: DemandeCreee, reveler: boolean): Partial<DemandeCreee> {
+  if (reveler) return creee
+  const { url_portail: _url_portail, ...reste } = creee
+  return reste
+}
+
+/**
+ * Refuse un fil qui n'est pas celui de la personne connectée.
+ *
+ * ⚠️ La réponse est la MÊME (404) dans les deux cas de refus : confirmer
+ * l'existence d'une demande qu'on n'a pas le droit de lire, c'est déjà une
+ * information (elle existe, elle est de cette app, quelqu'un d'autre l'a
+ * écrite).
+ *
+ * ⚠️ Mais les deux cas ne se journalisent pas pareil, et c'est le point de
+ * cette fonction. « L'adresse ne correspond pas » est un refus NORMAL, celui
+ * pour lequel la garde existe. « La réponse de l'API v1 ne porte pas
+ * `requerant_email` » est une rupture de contrat : la garde refuse alors
+ * TOUT LE MONDE, l'onglet « Mes demandes » liste des demandes qu'aucun clic
+ * n'ouvre, et rien dans la réponse HTTP ne distingue cette panne totale d'un
+ * fil qui appartient à quelqu'un d'autre. Le `detail` — qui ne sort jamais
+ * vers le navigateur, seulement vers `journaliserRelais` — est ce qui évite
+ * de chercher pendant une journée une garde qui fonctionne trop bien.
+ */
+function exigerAppartenance(lue: DemandeLue, identite: IdentiteRequerant): void {
+  const email = lue?.demande?.requerant_email
+  if (verifierAppartenance(email, identite.email)) return
+  const absent = typeof email !== 'string' || email.trim() === ''
+  throw new ErreurSupport({
+    code: 'introuvable',
+    message: "Cette demande n'existe pas.",
+    detail: absent
+      ? "la réponse de GET /demandes/:id ne porte pas requerant_email : la garde d'appartenance refuse alors TOUTES les lectures, y compris légitimes"
+      : undefined,
+  })
+}
+
+/* ─── Réponses ──────────────────────────────────────────────────────── */
+
+/**
+ * ⚠️ `Cache-Control: no-store` sur TOUTES les réponses.
+ *
+ * `/api/support/demandes` rend la liste d'UNE personne à une URL qui ne
+ * contient pas son nom. Un cache partagé (CDN, proxy d'entreprise, le cache
+ * de route de Next lui-même) qui la garderait trente secondes servirait le fil
+ * du premier visiteur au deuxième. Rien ne le signalerait : les deux réponses
+ * sont valides, c'est leur destinataire qui est faux.
+ */
+const ENTETES_BASE: Record<string, string> = {
+  'Content-Type': 'application/json; charset=utf-8',
+  'Cache-Control': 'no-store',
+}
+
+function reponse(statut: number, corps: unknown, entetes: Record<string, string> = {}): Response {
+  return new Response(JSON.stringify(corps), {
+    status: statut,
+    headers: { ...ENTETES_BASE, ...entetes },
+  })
+}
+
+function reponseOk(donnees: unknown, statut: number): Response {
+  return reponse(statut, donnees)
+}
+
+function reponseErreur(
+  statut: number,
+  code: string,
+  message: string,
+  entetes: Record<string, string> = {},
+): Response {
+  return reponse(statut, { erreur: { code, message } }, entetes)
+}
+
+/**
+ * Traduit une erreur du client en réponse HTTP, sans jamais fuir de détail.
+ *
+ * ⚠️ Le message d'une erreur inconnue n'est PAS recopié : il peut contenir
+ * l'URL complète appelée, donc l'hôte de Support et parfois la clé si un
+ * intermédiaire l'a mise dans une trace. Le générique suffit ; le détail part
+ * dans `journaliser`. Même raison pour `detail` d'une `ErreurSupport` : il est
+ * écrit pour le journal, jamais pour l'écran, et il n'entre donc pas dans le
+ * corps rendu.
+ *
+ * ⚠️ `Retry-After` est REPOSÉ sur un 429. Support l'envoie, le client le lit
+ * pour son propre réessai — et sans cette ligne, il s'arrêtait là : le
+ * navigateur recevait une limite sans savoir quand revenir, et c'est
+ * exactement ce qui reconstruit la rafale qu'on limitait. Un en-tête perdu
+ * dans un relais ne se voit dans aucun test qui ne regarde que le corps.
+ */
+export function traduireErreur(erreur: unknown): {
+  statut: number
+  corps: unknown
+  entetes?: Record<string, string>
+} {
+  if (estErreurSupport(erreur)) {
+    const statut = STATUT_PAR_CODE[erreur.code] ?? 500
+    const secondes =
+      typeof erreur.retryApresMs === 'number' && Number.isFinite(erreur.retryApresMs)
+        ? Math.max(1, Math.ceil(erreur.retryApresMs / 1000))
+        : null
+    return {
+      statut,
+      corps: {
+        erreur: {
+          code: erreur.code,
+          message: erreur.message,
+          ...(erreur.champs ? { champs: erreur.champs } : {}),
+        },
+      },
+      ...(statut === 429 && secondes !== null
+        ? { entetes: { 'Retry-After': String(secondes) } }
+        : {}),
+    }
+  }
+  return { statut: 500, corps: { erreur: { code: 'interne', message: MESSAGE_GENERIQUE } } }
+}
+
+/** Miroir de `STATUT_PAR_CODE` de Support, plus les codes du client. */
+const STATUT_PAR_CODE: Record<string, number> = {
+  cle_invalide: 401,
+  app_inactive: 403,
+  introuvable: 404,
+  conflit: 409,
+  validation: 422,
+  limite: 429,
+  interne: 500,
+  // Côté relais, une panne de configuration ou de réseau est une
+  // indisponibilité de SERVICE, pas une faute du navigateur : 503 invite à
+  // réessayer, 500 laisse croire à un bug de la requête.
+  configuration: 503,
+  reseau: 503,
+  delai: 504,
+  cle_exposee: 500,
+}
+
+async function lireJson(requete: Request): Promise<unknown> {
+  try {
+    return await requete.json()
+  } catch {
+    // Un corps illisible donne un objet vide, que la validation de Support
+    // refusera en nommant les champs manquants. C'est un meilleur message que
+    // « Unexpected token < in JSON at position 0 ».
+    return {}
+  }
+}