CSRF-Schutz

Diese Middleware schützt vor CSRF-Angriffen, indem sie sowohl den Header Origin als auch Sec-Fetch-Site prüft. Die Anfrage wird zugelassen, wenn eine der beiden Prüfungen erfolgreich ist.

Die Middleware prüft nur Anfragen, die:

• unsichere HTTP-Methoden verwenden, also nicht GET, HEAD oder OPTIONS
• Inhaltstypen verwenden, die von HTML-Formularen gesendet werden können (application/x-www-form-urlencoded, multipart/form-data oder text/plain)

Alte Browser, die keine Header Origin senden, oder Umgebungen, in denen Reverse-Proxys diese Header entfernen, funktionieren möglicherweise nicht korrekt. Verwende in solchen Umgebungen andere Verfahren mit CSRF-Tokens.

Import

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

Verwendung

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
    },
  })
)

Optionen

optional origin: string | string[] | Function

Gib die für den CSRF-Schutz erlaubten Origins an.

• string: Eine einzelne erlaubte Origin, z. B. 'https://example.com'
• string[]: Ein Array erlaubter Origins
• Function: Ein eigener Handler (origin: string, context: Context) => boolean für flexible Origin-Prüfungen und Ausnahmeregeln

Standard: Nur dieselbe Origin wie die Anfrage-URL

Der Funktions-Handler erhält den Wert des Anfrage-Headers Origin und den Anfragekontext. Damit sind dynamische Prüfungen anhand von Anfrageeigenschaften wie Pfad, Headern oder weiteren Kontextdaten möglich.

optional secFetchSite: string | string[] | Function

Gib die erlaubten Werte des Headers Sec-Fetch-Site für CSRF-Schutz mit Fetch Metadata an.

• string: Ein einzelner erlaubter Wert, z. B. 'same-origin'
• string[]: Ein Array erlaubter Werte, z. B. ['same-origin', 'none']
• Function: Ein eigener Handler (secFetchSite: string, context: Context) => boolean für flexible Prüfungen

Standard: Nur 'same-origin' ist erlaubt

Standardwerte für Sec-Fetch-Site:

• same-origin: Anfrage von derselben Origin
• same-site: Anfrage von derselben Website mit einer anderen Subdomain
• cross-site: Anfrage von einer anderen Website
• none: Anfrage, die nicht von einer Webseite stammt, etwa aus der Browser-Adressleiste oder einem Lesezeichen

Der Funktions-Handler erhält den Wert des Anfrage-Headers Sec-Fetch-Site und den Anfragekontext. So sind dynamische Prüfungen anhand der Anfrageeigenschaften möglich.