@zevra/support 0.2.0

package/src/erreurs.ts

@@ -0,0 +1,199 @@
+// ============================================================================
+// Les échecs, typés. PUR.
+// ============================================================================
+//
+// Miroir de `src/lib/reponse-api.ts` côté Support : la liste des codes y est
+// FERMÉE, et ce fichier est la raison pour laquelle elle l'est. Un code que le
+// SDK ne connaît pas tombe dans le `catch` générique de l'app cliente, qui
+// affiche « erreur inconnue » sur un 422 parfaitement explicite.
+//
+// Trois codes de PLUS ici, qui ne viennent jamais du fil : `reseau`, `delai`
+// et `configuration`. Les confondre avec `interne` (« le serveur a un
+// problème ») enverrait chercher une panne chez Support alors que le DNS de
+// l'appelant ne résout pas, ou que personne n'a créé `SUPPORT_API_KEY`.
+
+/** Ce que l'API peut répondre — recopié de `STATUT_PAR_CODE` de Support. */
+export const CODES_DU_FIL = [
+  'cle_invalide',
+  'app_inactive',
+  'introuvable',
+  'validation',
+  'conflit',
+  'limite',
+  // ⚠️ Ajouté à l'intégration, en même temps que la ligne `non_configure: 503`
+  // de `src/lib/reponse-api.ts`. Trois routes le rendent déjà (`POST /pieces`
+  // sans S3, `/api/admin/*` sans clé, `/api/cron/*` sans `CRON_SECRET`) : sans
+  // lui ici, une réponse parfaitement légitime tombait dans le repli `interne`
+  // et l'intégrateur lisait « le serveur a un problème » là où il fallait lire
+  // « personne n'a encore créé la variable ». Un 503 ne se réessaie pas en
+  // boucle : il attend qu'un humain passe dans l'admin.
+  'non_configure',
+  'interne',
+] as const
+
+/** Ce que seul le client peut conclure. Ne vient JAMAIS d'une réponse HTTP. */
+export const CODES_DU_CLIENT = ['reseau', 'delai', 'configuration', 'cle_exposee'] as const
+
+export const CODES_ERREUR = [...CODES_DU_FIL, ...CODES_DU_CLIENT] as const
+
+export type CodeErreurSupport = (typeof CODES_ERREUR)[number]
+
+/** `true` seulement pour un code que l'API a réellement le droit d'écrire. */
+export function estCodeDuFil(valeur: unknown): valeur is (typeof CODES_DU_FIL)[number] {
+  return typeof valeur === 'string' && (CODES_DU_FIL as readonly string[]).includes(valeur)
+}
+
+/**
+ * Le message générique.
+ *
+ * ⚠️ Il est CONSTANT. Recopier le corps brut d'un 502 dans le message, c'est
+ * afficher la page d'erreur HTML d'un proxy dans l'interface d'un utilisateur.
+ * Le brut part dans `detail`, borné, pour la journalisation.
+ */
+export const MESSAGE_GENERIQUE = "Le support n'a pas pu traiter cette requête."
+
+/** Au-delà, ce n'est plus un indice, c'est une page HTML entière dans un log. */
+export const LONGUEUR_DETAIL_MAX = 200
+
+export interface DonneesErreurSupport {
+  code: CodeErreurSupport
+  message: string
+  /** Rempli seulement sur `validation` : un message par champ fautif. */
+  champs?: Record<string, string>
+  /** Ce qu'on a vraiment reçu, tronqué. Pour le journal, pas pour l'écran. */
+  detail?: string
+  statut?: number
+  /** Sur `limite` : l'attente demandée, déjà convertie. */
+  retryApresMs?: number
+}
+
+export class ErreurSupport extends Error {
+  readonly code: CodeErreurSupport
+  readonly champs?: Record<string, string>
+  readonly detail?: string
+  readonly statut?: number
+  readonly retryApresMs?: number
+
+  constructor(donnees: DonneesErreurSupport) {
+    super(donnees.message)
+    this.name = 'ErreurSupport'
+    this.code = donnees.code
+    this.champs = donnees.champs
+    this.detail = donnees.detail
+    this.statut = donnees.statut
+    this.retryApresMs = donnees.retryApresMs
+  }
+}
+
+export function estErreurSupport(valeur: unknown): valeur is ErreurSupport {
+  return valeur instanceof ErreurSupport
+}
+
+/** Borne un texte brut : ce qui dépasse est remplacé par une ellipse. */
+export function bornerDetail(brut: unknown): string | undefined {
+  if (typeof brut !== 'string') {
+    if (brut === undefined || brut === null) return undefined
+    try {
+      return bornerDetail(JSON.stringify(brut))
+    } catch {
+      return undefined
+    }
+  }
+  const compacte = brut.replace(/\s+/g, ' ').trim()
+  if (compacte === '') return undefined
+  return compacte.length > LONGUEUR_DETAIL_MAX
+    ? `${compacte.slice(0, LONGUEUR_DETAIL_MAX)}…`
+    : compacte
+}
+
+export interface EchecHttp {
+  statut: number
+  /** Le corps DÉJÀ décodé si c'était du JSON, sinon le texte brut. */
+  corps: unknown
+  retryApresMs?: number | null
+}
+
+/**
+ * Traduit une réponse en échec d'un des codes fermés. PUR.
+ *
+ * ⚠️ Le cas « on ne peut pas conclure » reste distinct de « c'est faux » :
+ * un corps illisible, un code inconnu, un statut inattendu donnent `interne`
+ * — pas une invention. Et le brut est conservé dans `detail`, sans quoi un
+ * incident se résume à « erreur 500 » et personne ne sait chez qui chercher.
+ */
+export function interpreterEchec(echec: EchecHttp): DonneesErreurSupport {
+  const enveloppe = lireEnveloppe(echec.corps)
+  const retryApresMs =
+    typeof echec.retryApresMs === 'number' && Number.isFinite(echec.retryApresMs)
+      ? echec.retryApresMs
+      : undefined
+
+  if (enveloppe && estCodeDuFil(enveloppe.code)) {
+    return {
+      code: enveloppe.code,
+      message: enveloppe.message ?? MESSAGE_GENERIQUE,
+      champs: enveloppe.code === 'validation' ? enveloppe.champs : undefined,
+      statut: echec.statut,
+      retryApresMs,
+    }
+  }
+
+  // Un code hors liste (une version d'API plus récente, un proxy bavard) : on
+  // ne le PROPAGE pas sous son nom — l'appelant ne peut pas s'y brancher, et
+  // lui donner l'air officiel ferait croire à un contrat qui n'existe pas.
+  return {
+    code: codeParDefautPourStatut(echec.statut),
+    message: MESSAGE_GENERIQUE,
+    detail: bornerDetail(echec.corps),
+    statut: echec.statut,
+    retryApresMs,
+  }
+}
+
+/**
+ * Le repli quand le corps ne dit rien d'exploitable.
+ *
+ * On déduit du STATUT, qui vient au moins d'une couche HTTP réelle : un 429
+ * posé par un proxy reste une limite, et le réessai doit le savoir même si le
+ * corps est une page HTML.
+ */
+function codeParDefautPourStatut(statut: number): CodeErreurSupport {
+  if (statut === 401) return 'cle_invalide'
+  if (statut === 403) return 'app_inactive'
+  if (statut === 404) return 'introuvable'
+  if (statut === 409) return 'conflit'
+  if (statut === 422) return 'validation'
+  if (statut === 429) return 'limite'
+  // ⚠️ 503 SEULEMENT, pas 502 ni 504 : ces deux-là viennent d'un proxy qui n'a
+  // pas joint le service, ce qui est bien une panne. Un 503 de Support, lui,
+  // est écrit par Support et dit « capacité non branchée ».
+  if (statut === 503) return 'non_configure'
+  return 'interne'
+}
+
+interface EnveloppeErreur {
+  code?: unknown
+  message?: string
+  champs?: Record<string, string>
+}
+
+function lireEnveloppe(corps: unknown): EnveloppeErreur | null {
+  if (typeof corps !== 'object' || corps === null) return null
+  const erreur = (corps as { erreur?: unknown }).erreur
+  if (typeof erreur !== 'object' || erreur === null) return null
+  const brut = erreur as Record<string, unknown>
+  const champs =
+    typeof brut.champs === 'object' && brut.champs !== null
+      ? (Object.fromEntries(
+          Object.entries(brut.champs as Record<string, unknown>).map(([cle, valeur]) => [
+            cle,
+            String(valeur),
+          ]),
+        ) as Record<string, string>)
+      : undefined
+  return {
+    code: brut.code,
+    message: typeof brut.message === 'string' ? brut.message : undefined,
+    champs,
+  }
+}

package/src/garde-serveur.ts

@@ -0,0 +1,75 @@
+// ============================================================================
+// La garde qui rend l'erreur de clé IMPOSSIBLE, pas seulement déconseillée.
+// ============================================================================
+//
+// POURQUOI. La clé `sk_support_<slug>_<32 hex>` authentifie l'APP ENTIÈRE. Qui
+// la détient peut créer une demande au nom de n'importe quelle adresse, relire
+// tous les fils de l'app, et lire le contexte technique que les utilisateurs y
+// ont déposé. Dans un bundle de navigateur, elle est en clair : l'onglet
+// Réseau la montre, `view-source` la montre, et une extension la lit. Elle ne
+// se révoque qu'en la faisant tourner — c'est-à-dire en cassant l'intégration
+// de l'app en production.
+//
+// CE QUI REND L'ERREUR FACILE. Dans une app Next, `src/` mélange serveur et
+// client. Un composant marqué `'use client'` qui importe le client du SDK
+// « pour tester vite fait » emporte la clé dans le bundle SANS AUCUNE ERREUR :
+// `process.env.SUPPORT_API_KEY` y vaut `undefined` (Next ne fige que les
+// `NEXT_PUBLIC_*`), l'appel échoue en 401, on « répare » en renommant la
+// variable `NEXT_PUBLIC_SUPPORT_API_KEY` — et la clé part en production dans
+// le JavaScript de chaque page. Ce chemin-là a été parcouru par de vrais
+// projets ; il ne commence jamais par une mauvaise intention.
+//
+// CE QU'ON FAIT. Le module qui LIT la clé appelle `exigerServeur()`. Dans un
+// navigateur, il jette immédiatement, au chargement, avec la marche à suivre —
+// au lieu d'échouer plus tard, en 401, avec un message qui ne dit rien.
+//
+// ⚠️ `import 'server-only'` (le paquet de Next) ferait la même garde À LA
+// COMPILATION, ce qui est mieux : l'erreur arrive au build, pas à l'exécution.
+// Il n'est PAS employé ici parce que ce paquet ne doit avoir aucune dépendance
+// (il doit s'installer dans une app Node, Bun ou edge qui n'a pas Next). Les
+// apps Next qui le veulent peuvent ajouter la ligne dans LEUR fichier de
+// relais : les deux gardes se complètent, elles ne se remplacent pas.
+
+import { ErreurSupport } from './erreurs'
+
+/** La portée globale, réduite à ce qu'on observe. Injectable : c'est ce qui
+ *  rend la décision testable sans monter un navigateur. */
+export interface PorteeObservee {
+  window?: unknown
+  document?: unknown
+}
+
+/**
+ * « Sommes-nous dans un navigateur ? » PUR.
+ *
+ * On exige les DEUX (`window` ET `document`) : un worker de service a un
+ * `self` mais pas de `document`, jsdom a les deux, Node n'a ni l'un ni
+ * l'autre. Se contenter de `window` refuserait des runtimes serveur légitimes
+ * qui en définissent un vide.
+ */
+export function estNavigateur(portee: PorteeObservee | undefined | null): boolean {
+  if (!portee) return false
+  return (
+    typeof portee.window === 'object' &&
+    portee.window !== null &&
+    typeof portee.document === 'object' &&
+    portee.document !== null
+  )
+}
+
+export const MESSAGE_CLE_EXPOSEE =
+  "@zevra/support est un client SERVEUR : il détient la clé sk_support_… et " +
+  'ne doit jamais être importé dans du code de navigateur. Depuis un composant ' +
+  "client, appelez les routes /api/support/* de votre app (creerRoutesSupport), " +
+  'jamais le support directement.'
+
+/**
+ * Jette si on est dans un navigateur. Appelée par tout module qui lit la clé.
+ *
+ * Le défaut lit `globalThis`, ce qui la rend impure — d'où la séparation :
+ * la DÉCISION est `estNavigateur`, cette fonction n'est que son bras armé.
+ */
+export function exigerServeur(portee: PorteeObservee = globalThis as PorteeObservee): void {
+  if (!estNavigateur(portee)) return
+  throw new ErreurSupport({ code: 'cle_exposee', message: MESSAGE_CLE_EXPOSEE })
+}

package/src/index.ts

@@ -0,0 +1,117 @@
+// ============================================================================
+// @zevra/support — le client SERVEUR de Zevra Support.
+// ============================================================================
+//
+// ⚠️ CE TONNEAU N'EST PAS IMPORTABLE DEPUIS UN NAVIGATEUR, et c'est délibéré :
+// `creerClientSupport()` appelle `exigerServeur()` dès sa première ligne et
+// jette si `window` et `document` existent. Voir `garde-serveur.ts` pour le
+// raisonnement complet — en deux mots : la clé `sk_support_…` authentifie
+// l'app ENTIÈRE, elle est lisible en clair dans un bundle, et le chemin qui
+// l'y amène ne commence jamais par une mauvaise intention.
+//
+// Ce qu'un composant client doit importer : RIEN d'ici. Il appelle les routes
+// `/api/support/*` que `creerRoutesSupport()` installe dans l'app, ou il pose
+// `<WidgetSupport />` de `@zevra/support-widget`, qui ne fait que ça.
+//
+// ⚠️ Rien de ce qui est exporté ci-dessous ne PREND une clé en paramètre
+// depuis l'extérieur, sauf `creerClientSupport` — qui est aussi le seul à
+// porter la garde. Cette symétrie est le contrat : si un jour une fonction
+// exportée accepte une clé sans passer par le client, elle doit appeler
+// `exigerServeur()` elle-même.
+
+export { creerClientSupport } from './client'
+export type {
+  ClientSupport,
+  EvenementClient,
+  OptionsAppel,
+  OptionsClientSupport,
+} from './client'
+
+export { lireConfiguration, slugDeCle, PREFIXE_CLE } from './configuration'
+export type { EntreeConfiguration, EtatConfiguration } from './configuration'
+
+export {
+  CODES_DU_CLIENT,
+  CODES_DU_FIL,
+  CODES_ERREUR,
+  ErreurSupport,
+  MESSAGE_GENERIQUE,
+  estCodeDuFil,
+  estErreurSupport,
+  interpreterEchec,
+} from './erreurs'
+export type { CodeErreurSupport, DonneesErreurSupport, EchecHttp } from './erreurs'
+
+export { estNavigateur, exigerServeur, MESSAGE_CLE_EXPOSEE } from './garde-serveur'
+
+export {
+  ENTETE_CLE,
+  ENTETE_IDEMPOTENCE,
+  SEGMENT_API,
+  TAILLE_MAX_CORPS_OCTETS,
+  normaliserBase,
+  octetsUtf8,
+  preparerRequete,
+  serialiserQuery,
+} from './requete'
+export type { EntreeRequete, RequetePreparee, ValeurQuery } from './requete'
+
+export {
+  BUDGET_MS_DEFAUT,
+  DELAI_BASE_MS,
+  DELAI_REQUETE_MS_DEFAUT,
+  MAX_TENTATIVES_DEFAUT,
+  analyserRetryApres,
+  deciderReessai,
+  delaiExponentiel,
+} from './reessai'
+export type { DecisionReessai, EntreeDecision, RaisonAbandon, RaisonReessai } from './reessai'
+
+export { creerRoutesSupport, filtrerCreation, traduireErreur } from './relais/routes'
+export type {
+  ContexteRoute,
+  GestionnaireRoute,
+  OptionsRoutesSupport,
+  RoutesSupport,
+} from './relais/routes'
+
+export { estIdentifiantPlausible, resoudreRelais } from './relais/chemins'
+export type { ActionRelais, ResolutionRelais } from './relais/chemins'
+
+export {
+  CHAMPS_CREATION_ACCEPTES,
+  LONGUEUR_TITRE,
+  MAX_ERREURS_CONSOLE,
+  bornerContexte,
+  composerCreation,
+  composerDepotPiece,
+  composerListe,
+  composerMessage,
+  normaliserEmail,
+  verifierAppartenance,
+} from './relais/corps'
+export type { IdentiteRequerant } from './relais/corps'
+
+export { TYPES_DEMANDE } from './types'
+export type {
+  AuteurMessage,
+  ContexteDemande,
+  DemandeCreee,
+  DemandeLue,
+  DepotPiece,
+  EntreeAjouterMessage,
+  EntreeCreerDemande,
+  EntreeDeposerPiece,
+  EntreeListerDemandes,
+  MessageAjoute,
+  MessageLu,
+  PageDemandes,
+  PieceLue,
+  PrioriteDemande,
+  ProgrammeActif,
+  Requerant,
+  ResumeDemande,
+  ScenarioCampagne,
+  StatutDemande,
+  TypeDemande,
+} from './types'

package/src/reessai.ts

@@ -0,0 +1,134 @@
+// ============================================================================
+// Réessayer, ou renoncer et le dire. PUR — ni horloge, ni hasard, ni sommeil.
+// ============================================================================
+//
+// L'API v1 limite à 60 requêtes / minute / app et répond 429 avec un
+// `Retry-After` (PLAN.md §4). Un client qui l'ignore reconstruit exactement la
+// rafale qu'on limitait ; un client qui réessaie éternellement fait attendre
+// la personne qui a cliqué sans jamais le lui dire. D'où deux bornes, et une
+// troisième décision : ce qu'on ne réessaie PAS.
+
+/** Ce qui se retente : la panne passagère et la limite. */
+export type RaisonReessai = 'limite' | 'panne' | 'reseau'
+
+/** Ce qui ne se retente pas. Trois motifs DISTINCTS, exprès. */
+export type RaisonAbandon = 'definitif' | 'tentatives_epuisees' | 'budget_epuise'
+
+export type DecisionReessai =
+  | { reessayer: true; attendreMs: number; raison: RaisonReessai }
+  | { reessayer: false; raison: RaisonAbandon }
+
+/** Premier palier d'attente, doublé à chaque tentative. */
+export const DELAI_BASE_MS = 500
+
+/** Trois tentatives au total (l'originale + deux reprises). */
+export const MAX_TENTATIVES_DEFAUT = 3
+
+/** Budget total, réessais et attentes compris. Au-delà, on rend la main. */
+export const BUDGET_MS_DEFAUT = 25_000
+
+/** Délai par requête isolée. Une requête qui ne répond pas n'est pas gratuite. */
+export const DELAI_REQUETE_MS_DEFAUT = 10_000
+
+export interface EntreeDecision {
+  /** Le statut HTTP, ou `null` quand rien n'est revenu (réseau, délai). */
+  statut: number | null
+  /** La valeur brute de `Retry-After`, telle que lue dans les en-têtes. */
+  retryApres?: string | null
+  /** 1 pour la première tentative. */
+  tentative: number
+  maxTentatives?: number
+  /** Millisecondes déjà consommées depuis le premier appel. */
+  ecouleMs: number
+  budgetMs?: number
+  /** Instant de référence pour un `Retry-After` en date HTTP. */
+  maintenant: Date
+  /** Gigue, dans [0, 1[. Injectée : le hasard n'a pas sa place dans un test. */
+  gigue?: number
+}
+
+/**
+ * Lit `Retry-After`. PUR.
+ *
+ * Deux formes légales (RFC 9110) : un nombre de secondes, ou une date HTTP.
+ *
+ * ⚠️ Rend `null` quand la valeur est illisible, et ce `null` compte : rendre
+ * `0` pour « je n'ai pas compris » relancerait la requête dans l'instant, sur
+ * un serveur qui vient précisément de dire qu'il en recevait trop. « On ne
+ * peut pas conclure » doit rester distinct de « attendre zéro ».
+ */
+export function analyserRetryApres(
+  valeur: string | null | undefined,
+  maintenant: Date,
+): number | null {
+  if (valeur === null || valeur === undefined) return null
+  const detoure = String(valeur).trim()
+  if (detoure === '') return null
+
+  // Forme « secondes ». `Number('12abc')` vaut NaN, ce qu'on veut : une valeur
+  // à moitié numérique est une valeur qu'on n'a pas comprise.
+  if (/^\d+$/.test(detoure)) {
+    const secondes = Number(detoure)
+    return Number.isFinite(secondes) ? secondes * 1000 : null
+  }
+
+  const date = new Date(detoure)
+  const instant = date.getTime()
+  if (!Number.isFinite(instant)) return null
+  // Une date déjà passée vaut « tout de suite », pas une attente négative.
+  return Math.max(0, instant - maintenant.getTime())
+}
+
+/** Le palier d'attente d'une tentative, gigue comprise. PUR. */
+export function delaiExponentiel(tentative: number, gigue: number): number {
+  const palier = DELAI_BASE_MS * 2 ** Math.max(0, tentative - 1)
+  // La gigue ne fait qu'ÉTALER : elle ajoute jusqu'à un palier, elle ne
+  // raccourcit jamais. Deux clients partis en même temps doivent diverger,
+  // pas se retrouver plus tôt.
+  const borne = Math.min(Math.max(gigue, 0), 0.999)
+  return Math.round(palier * (1 + borne))
+}
+
+/**
+ * Faut-il réessayer, et après combien de temps ? PUR.
+ *
+ * Ce qui se réessaie : 429 (limite), 408 (délai côté serveur), 5xx (panne
+ * passagère), et l'absence de réponse (`statut: null`). Tout le reste est
+ * DÉFINITIF : réessayer un 422 renvoie le même corps invalide trois fois, et
+ * réessayer un 401 fait compter trois échecs d'authentification à une clé
+ * qu'on pourrait finir par bloquer.
+ */
+export function deciderReessai(entree: EntreeDecision): DecisionReessai {
+  const maxTentatives = entree.maxTentatives ?? MAX_TENTATIVES_DEFAUT
+  const budgetMs = entree.budgetMs ?? BUDGET_MS_DEFAUT
+  const statut = entree.statut
+
+  const raison = raisonDeReessayer(statut)
+  if (raison === null) return { reessayer: false, raison: 'definitif' }
+
+  if (entree.tentative >= maxTentatives) {
+    return { reessayer: false, raison: 'tentatives_epuisees' }
+  }
+
+  const demande = analyserRetryApres(entree.retryApres, entree.maintenant)
+  const attendreMs =
+    demande !== null ? demande : delaiExponentiel(entree.tentative, entree.gigue ?? 0)
+
+  // ⚠️ On ne RABOTE PAS une attente trop longue : un `Retry-After: 120`
+  // ramené à 30 s repartirait avant l'heure et récolterait un 429 de plus.
+  // Quand l'attente ne tient pas dans le budget, on renonce en le disant —
+  // l'appelant peut alors afficher « réessayez dans deux minutes » plutôt que
+  // de faire patienter quelqu'un devant un formulaire figé.
+  const restantMs = budgetMs - entree.ecouleMs
+  if (attendreMs >= restantMs) return { reessayer: false, raison: 'budget_epuise' }
+
+  return { reessayer: true, attendreMs, raison }
+}
+
+function raisonDeReessayer(statut: number | null): RaisonReessai | null {
+  if (statut === null) return 'reseau'
+  if (statut === 429) return 'limite'
+  if (statut === 408) return 'panne'
+  if (statut >= 500 && statut <= 599) return 'panne'
+  return null
+}

package/src/relais/chemins.ts

@@ -0,0 +1,91 @@
+// ============================================================================
+// Le plan des routes `/api/support/*`. PUR.
+// ============================================================================
+//
+// ⚠️ CE FICHIER EST UNE LISTE BLANCHE, ET C'EST TOUT SON INTÉRÊT.
+//
+// La tentation, en écrivant un relais, est de recoller les segments reçus sur
+// la base de l'API et de transmettre : trois lignes, ça marche tout de suite.
+// Ce relais-là donne à n'importe quel visiteur la clé de l'app comme
+// laissez-passer. Un `POST /api/support/../admin/apps` atteint l'endpoint
+// d'administration ; un `GET /api/support/demandes?email=pdg@client.fr` lit le
+// fil de quelqu'un d'autre. Rien n'a l'air cassé : le relais fait exactement
+// ce qu'on lui a demandé.
+//
+// Donc : six actions, nommées une par une. Ce qui n'est pas dans cette table
+// n'existe pas, et la réponse est la même (404) pour une route inconnue que
+// pour une route d'administration — on n'apprend pas au visiteur ce qui existe
+// derrière.
+
+/** Les six gestes que le navigateur a le droit de demander. */
+export type ActionRelais =
+  | 'creer_demande'
+  | 'lister_demandes'
+  | 'lire_demande'
+  | 'ajouter_message'
+  | 'deposer_piece'
+  | 'programme_actif'
+
+export type ResolutionRelais =
+  | { action: ActionRelais; demandeId?: string }
+  | { refus: 'chemin_inconnu' }
+  | { refus: 'methode_refusee'; permises: readonly string[] }
+
+/**
+ * Un identifiant de demande doit RESSEMBLER à un uuid.
+ *
+ * ⚠️ Ce n'est pas un contrôle d'existence, c'est un contrôle de FORME : sans
+ * lui, `demandes/..%2F..%2Fadmin` arrive dans une URL concaténée. Et le socle
+ * de Support l'exige aussi de son côté — un identifiant mal formé y rend
+ * `null`, pas une erreur 500.
+ */
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i
+
+export function estIdentifiantPlausible(valeur: string): boolean {
+  return UUID.test(valeur)
+}
+
+/**
+ * Résout un chemin du relais. PUR, total : ne jette jamais.
+ *
+ * `segments` est ce que Next donne dans `params.chemin` pour une route
+ * attrape-tout `app/api/support/[...chemin]/route.ts`, donc DÉJÀ décodé —
+ * d'où le contrôle de forme plutôt qu'un simple refus des `..` textuels.
+ */
+export function resoudreRelais(
+  segments: readonly string[] | undefined,
+  methode: string,
+): ResolutionRelais {
+  const chemin = (segments ?? []).filter((s) => s !== '')
+  const verbe = String(methode ?? '').toUpperCase()
+
+  if (chemin.length === 1 && chemin[0] === 'demandes') {
+    if (verbe === 'POST') return { action: 'creer_demande' }
+    if (verbe === 'GET') return { action: 'lister_demandes' }
+    return { refus: 'methode_refusee', permises: ['GET', 'POST'] }
+  }
+
+  if (chemin.length === 2 && chemin[0] === 'demandes') {
+    if (!estIdentifiantPlausible(chemin[1])) return { refus: 'chemin_inconnu' }
+    if (verbe === 'GET') return { action: 'lire_demande', demandeId: chemin[1] }
+    return { refus: 'methode_refusee', permises: ['GET'] }
+  }
+
+  if (chemin.length === 3 && chemin[0] === 'demandes' && chemin[2] === 'messages') {
+    if (!estIdentifiantPlausible(chemin[1])) return { refus: 'chemin_inconnu' }
+    if (verbe === 'POST') return { action: 'ajouter_message', demandeId: chemin[1] }
+    return { refus: 'methode_refusee', permises: ['POST'] }
+  }
+
+  if (chemin.length === 1 && chemin[0] === 'pieces') {
+    if (verbe === 'POST') return { action: 'deposer_piece' }
+    return { refus: 'methode_refusee', permises: ['POST'] }
+  }
+
+  if (chemin.length === 2 && chemin[0] === 'programmes' && chemin[1] === 'actif') {
+    if (verbe === 'GET') return { action: 'programme_actif' }
+    return { refus: 'methode_refusee', permises: ['GET'] }
+  }
+
+  return { refus: 'chemin_inconnu' }
+}