CSRF 保护

🌐 CSRF Protection

这个中间件通过检查 Origin 头和 Sec-Fetch-Site 头来防止 CSRF 攻击。如果任一验证通过，请求将被允许。

🌐 This middleware protects against CSRF attacks by checking both the Origin header and the Sec-Fetch-Site header. The request is allowed if either validation passes.

中间件仅验证以下请求：

🌐 The middleware only validates requests that:

• 使用不安全的 HTTP 方法（例如 GET、HEAD 或 OPTIONS）
• 具有可以通过 HTML 表单发送的内容类型（application/x-www-form-urlencoded、multipart/form-data 或 text/plain）

不发送 Origin 头的旧浏览器，或使用反向代理移除这些头的环境，可能无法正常工作。在这种环境下，请使用其他 CSRF 令牌方法。

🌐 Old browsers that do not send Origin headers, or environments that use reverse proxies to remove these headers, may not work well. In such environments, use other CSRF token methods.

导入

🌐 Import

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

用法

🌐 Usage

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

optional 来源：string | string[] | Function

指定允许的来源，以进行 CSRF 保护。

🌐 Specify allowed origins for CSRF protection.

• string：允许的单一来源（例如，'https://example.com'）
• string[]：允许的来源数组
• Function：用于灵活源验证和绕过逻辑的自定义处理程序 (origin: string, context: Context) => boolean

默认：仅与请求 URL 同源

函数处理程序接收请求的 Origin 头部值和请求上下文，从而可以基于请求属性（如路径、头部或其他上下文数据）进行动态验证。

🌐 The function handler receives the request's Origin header value and the request context, allowing for dynamic validation based on request properties like path, headers, or other context data.

optional secFetchSite: string | string[] | Function

使用 Fetch Metadata 为 CSRF 保护指定允许的 Sec-Fetch-Site 标头值。

🌐 Specify allowed Sec-Fetch-Site header values for CSRF protection using Fetch Metadata.

• string：允许的单一值（例如，'same-origin'）
• string[]：允许值的数组（例如，['same-origin', 'none']）
• Function：用于灵活验证的自定义处理器 (secFetchSite: string, context: Context) => boolean

默认：仅允许 'same-origin'

标准 Sec-Fetch-Site 值：

🌐 Standard Sec-Fetch-Site values:

• same-origin：来自相同来源的请求
• same-site：来自同一站点（不同子域名）的请求
• cross-site：来自不同站点的请求
• none：非来自网页（例如，浏览器地址栏、书签）的请求

函数处理程序接收请求的 Sec-Fetch-Site 头部值和请求上下文，从而能够根据请求属性进行动态验证。

🌐 The function handler receives the request's Sec-Fetch-Site header value and the request context, enabling dynamic validation based on request properties.