Protection CSRF

Ce middleware protège contre les attaques CSRF en vérifiant les en-têtes Origin et Sec-Fetch-Site. La requête est autorisée si l’une des deux validations réussit.

Le middleware ne valide que les requêtes qui :

• Utilisent des méthodes HTTP non sûres (autres que GET, HEAD ou OPTIONS)
• Ont un type de contenu pouvant être envoyé par un formulaire HTML (application/x-www-form-urlencoded, multipart/form-data ou text/plain)

Les anciens navigateurs qui n’envoient pas d’en-têtes Origin, ou les environnements utilisant des proxys inverses qui suppriment ces en-têtes, peuvent ne pas fonctionner correctement. Dans ces environnements, utilisez d’autres méthodes basées sur des jetons CSRF.

Importation

import { Hono } from 'hono'
import { csrf } from 'hono/csrf'

Utilisation

const app = new Hono()

// Default: both origin and sec-fetch-site validation
app.use(csrf())

// Allow specific origins
app.use(csrf({ origin: 'https://myapp.example.com' }))

// Allow multiple origins
app.use(
  csrf({
    origin: [
      'https://myapp.example.com',
      'https://development.myapp.example.com',
    ],
  })
)

// Allow specific sec-fetch-site values
app.use(csrf({ secFetchSite: 'same-origin' }))
app.use(csrf({ secFetchSite: ['same-origin', 'none'] }))

// Dynamic origin validation
// It is strongly recommended that the protocol be verified to ensure a match to `$`.
// You should *never* do a forward match.
app.use(
  '*',
  csrf({
    origin: (origin) =>
      /https:\/\/(\w+\.)?myapp\.example\.com$/.test(origin),
  })
)

// Dynamic sec-fetch-site validation
app.use(
  csrf({
    secFetchSite: (secFetchSite, c) => {
      // Always allow same-origin
      if (secFetchSite === 'same-origin') return true
      // Allow cross-site for webhook endpoints
      if (
        secFetchSite === 'cross-site' &&
        c.req.path.startsWith('/webhook/')
      ) {
        return true
      }
      return false
    },
  })
)

Options

facultatif origin: string | string[] | Function

Spécifie les origines autorisées pour la protection CSRF.

• string : Une seule origine autorisée (par exemple 'https://example.com')
• string[] : Un tableau des origines autorisées
• Function : Un gestionnaire personnalisé (origin: string, context: Context) => boolean pour une validation flexible de l’origine et une logique de contournement

Valeur par défaut : Uniquement l’origine de l’URL de la requête

La fonction reçoit la valeur de l’en-tête Origin de la requête et son contexte, ce qui permet une validation dynamique selon des propriétés comme le chemin, les en-têtes ou d’autres données de contexte.

facultatif secFetchSite: string | string[] | Function

Spécifie les valeurs d’en-tête Sec-Fetch-Site autorisées pour la protection CSRF à l’aide de Fetch Metadata.

• string : Une seule valeur autorisée (par exemple 'same-origin')
• string[] : Un tableau des valeurs autorisées (par exemple ['same-origin', 'none'])
• Function : Un gestionnaire personnalisé (secFetchSite: string, context: Context) => boolean pour une validation flexible

Valeur par défaut : Autorise uniquement 'same-origin'

Valeurs standard de Sec-Fetch-Site :

• same-origin : Requête provenant de la même origine
• same-site : Requête provenant du même site, mais d’un sous-domaine différent
• cross-site : Requête provenant d’un autre site
• none : Requête ne provenant pas d’une page web, par exemple de la barre d’adresse du navigateur ou d’un favori

La fonction reçoit la valeur de l’en-tête Sec-Fetch-Site de la requête et son contexte, ce qui permet une validation dynamique selon les propriétés de la requête.