Aller au contenu

HTTP Guardian

Refresh et CSRF

Refresh, CSRF et guards sensibles¶

Ces options changent le comportement en cas de 401, 419, 429 et mutations. Elles doivent être documentées dans l'application consommatrice.

Bearer refresh single-flight¶

import { bearerAuth, bearerRefreshGuard, createHttpClient } from "@cedvict/http-guardian";

const api = createHttpClient({
  baseUrl: "https://api.example.com",
  auth: bearerAuth(() => tokenStore.access()),
  parser,
  guards: [
    bearerRefreshGuard({
      refreshFn: () => tokenStore.refresh(),
      onTokenRefreshed: ({ accessToken }) => tokenStore.setAccess(accessToken),
      skipRefreshFor: (ctx) => ctx.url.includes("/auth/")
    })
  ]
});

Option	Défaut	Explication
`refreshFn`	Aucun	Fonction appelée une seule fois pour une vague de 401 concurrents.
`onTokenRefreshed`	Aucun point d'extension	Persiste le nouveau token avant le rejeu des requêtes en attente.
`skipRefreshFor`	Aucune exclusion applicative	Exclut login, refresh, logout, health ou endpoints publics.
`triggerStatuses`	`[401]`	Statuts qui déclenchent le refresh Bearer.
`queueTimeoutMs`	`30000`	Délai maximum d'attente pendant le refresh single-flight.

Boucle de refresh

refreshFn ne doit pas appeler le même client protégé sans noAuth, sinon le refresh peut se relancer lui-même.

cookieSafeRefreshGuard({
  refreshPath: "/auth/refresh",
  excludePaths: ["/auth/login", "/auth/refresh", "/health"]
})

Option	Défaut	Explication
`refreshPath`	Aucun	Endpoint dédié au refresh cookie.
`triggerStatuses`	`[401, 419]`	419 couvre souvent une session expirée ou un CSRF invalide.
`maxRetry`	`1`	Nombre de replays de la requête originale après refresh.
`excludePaths`	`[]`	Pathnames ignorés par la logique refresh.
`honorRetryAfter`	`true`	Respecte `Retry-After` ou applique un cooldown sur 429.

CSRF¶

csrfGuard({
  tokenFromCookie: "csrf_token",
  tokenFromHeader: "X-CSRF-Token",
  headerName: "X-CSRF-Token"
})

Option	Défaut	Explication
`tokenFromCookie`	Désactivé	Lit un cookie navigateur non HttpOnly.
`tokenFromHeader`	Désactivé	Mémorise la dernière valeur non vide d'un header réponse.
`headerName`	`X-CSRF-Token`	Header injecté sur les mutations.
`applyTo`	`POST`, `PUT`, `PATCH`, `DELETE`	Méthodes concernées.

Le backend doit exposer le header CSRF en CORS si le navigateur doit le lire.