Skip to main content
Bun 通过 Bun.CSRF 提供了一个内置 API，用于生成和验证 CSRF（跨站请求伪造）令牌。令牌使用 HMAC 签名，并包含过期时间戳以限制令牌的有效期窗口。
https://mintcdn.com/bun-zhcndoc/cnUTwgMuf4cCrwC-/icons/typescript.svg?fit=max&auto=format&n=cnUTwgMuf4cCrwC-&q=85&s=e7767043c9e885c34f2d6c8fe2a95217csrf.ts
// 生成令牌
const token = Bun.CSRF.generate("my-secret");

// 验证令牌
const isValid = Bun.CSRF.verify(token, { secret: "my-secret" });
console.log(isValid); // true

​
Bun.CSRF.generate()

生成 CSRF 令牌。令牌包含加密随机数（nonce）、时间戳和 HMAC 签名，编码为字符串。
https://mintcdn.com/bun-zhcndoc/cnUTwgMuf4cCrwC-/icons/typescript.svg?fit=max&auto=format&n=cnUTwgMuf4cCrwC-&q=85&s=e7767043c9e885c34f2d6c8fe2a95217generate.ts
const token = Bun.CSRF.generate("my-secret-key");
参数：
  • secret（string，可选）— 用于签署令牌的密钥。如果未提供，Bun 会生成一个随机的内存中默认密钥（每个线程唯一）。
  • options（object，可选）：
选项类型默认值描述
expiresInnumber86400000令牌过期的毫秒数。默认为 24 小时。
encodingstring"base64url"令牌编码格式："base64"、"base64url" 或 "hex"。
algorithmstring"sha256"HMAC 算法："sha256"、"sha384"、"sha512"、"sha512-256"、"blake2b256" 或 "blake2b512"。
返回： string — 编码后的令牌。
https://mintcdn.com/bun-zhcndoc/cnUTwgMuf4cCrwC-/icons/typescript.svg?fit=max&auto=format&n=cnUTwgMuf4cCrwC-&q=85&s=e7767043c9e885c34f2d6c8fe2a95217generate-options.ts
// 1 小时后过期的令牌，使用十六进制编码
const token = Bun.CSRF.generate("my-secret", {
  expiresIn: 60 * 60 * 1000,
  encoding: "hex",
});

// 使用不同的算法
const token2 = Bun.CSRF.generate("my-secret", {
  algorithm: "sha512",
});

​
Bun.CSRF.verify()

验证 CSRF 令牌。如果令牌有效且未过期，返回 true，否则返回 false。
https://mintcdn.com/bun-zhcndoc/cnUTwgMuf4cCrwC-/icons/typescript.svg?fit=max&auto=format&n=cnUTwgMuf4cCrwC-&q=85&s=e7767043c9e885c34f2d6c8fe2a95217verify.ts
const isValid = Bun.CSRF.verify(token, { secret: "my-secret-key" });
参数：
  • token（string，必需）— 要验证的令牌。
  • options（object，可选）：
选项类型默认值描述
secretstring(auto)用于签署令牌的密钥。如果未提供，则使用与 generate() 相同的内存中默认值。
maxAgenumber86400000令牌的最大存活时间（毫秒），独立于令牌自身的 expiresIn。
encodingstring"base64url"必须与 generate() 期间使用的编码匹配。
algorithmstring"sha256"必须与 generate() 期间使用的算法匹配。
返回： boolean
https://mintcdn.com/bun-zhcndoc/cnUTwgMuf4cCrwC-/icons/typescript.svg?fit=max&auto=format&n=cnUTwgMuf4cCrwC-&q=85&s=e7767043c9e885c34f2d6c8fe2a95217verify-options.ts
// 验证十六进制编码的令牌
const isValid = Bun.CSRF.verify(hexToken, {
  secret: "my-secret",
  encoding: "hex",
});

// 强制执行比生成令牌时更短的最大存活时间
const isValid2 = Bun.CSRF.verify(token, {
  secret: "my-secret",
  maxAge: 60 * 1000, // 拒绝超过 1 分钟的令牌
});

​
在 Bun.serve() 中使用

典型模式是在渲染表单时生成令牌，将其嵌入隐藏字段中，并在提交表单时进行验证。
https://mintcdn.com/bun-zhcndoc/cnUTwgMuf4cCrwC-/icons/typescript.svg?fit=max&auto=format&n=cnUTwgMuf4cCrwC-&q=85&s=e7767043c9e885c34f2d6c8fe2a95217server.ts
const SECRET = process.env.CSRF_SECRET || "my-secret";

const server = Bun.serve({
  routes: {
    "/form": () => {
      const token = Bun.CSRF.generate(SECRET);

      return new Response(
        `<form method="POST" action="/submit">
          <input type="hidden" name="_csrf" value="${token}" />
          <input type="text" name="message" />
          <button type="submit">发送</button>
        </form>`,
        { headers: { "Content-Type": "text/html" } },
      );
    },

    "/submit": {
      POST: async req => {
        const formData = await req.formData();
        const csrfToken = formData.get("_csrf");

        if (typeof csrfToken !== "string" || !Bun.CSRF.verify(csrfToken, { secret: SECRET })) {
          return new Response("无效的 CSRF 令牌", { status: 403 });
        }

        return new Response("成功");
      },
    },
  },
});

console.log(`监听于 ${server.url}`);

​
默认密钥

如果在 generate() 和 verify() 中都省略 secret 参数，Bun 会使用每个线程生成一次的随机密钥。这对于单线程应用很方便，但在多台服务器、多个 Worker 之间或重启后无法工作。
https://mintcdn.com/bun-zhcndoc/cnUTwgMuf4cCrwC-/icons/typescript.svg?fit=max&auto=format&n=cnUTwgMuf4cCrwC-&q=85&s=e7767043c9e885c34f2d6c8fe2a95217default-secret.ts
// 这两个调用在此运行时上下文中使用相同的每线程默认密钥。
const token = Bun.CSRF.generate();
const isValid = Bun.CSRF.verify(token); // true
对于生产环境，请始终提供跨基础设施共享的显式密钥。

​
TypeScript

https://mintcdn.com/bun-zhcndoc/cnUTwgMuf4cCrwC-/icons/typescript.svg?fit=max&auto=format&n=cnUTwgMuf4cCrwC-&q=85&s=e7767043c9e885c34f2d6c8fe2a95217types.ts
type CSRFAlgorithm = "blake2b256" | "blake2b512" | "sha256" | "sha384" | "sha512" | "sha512-256";

interface CSRFGenerateOptions {
  expiresIn?: number;
  encoding?: "base64" | "base64url" | "hex";
  algorithm?: CSRFAlgorithm;
}

interface CSRFVerifyOptions {
  secret?: string;
  encoding?: "base64" | "base64url" | "hex";
  algorithm?: CSRFAlgorithm;
  maxAge?: number;
}

namespace Bun.CSRF {
  function generate(secret?: string, options?: CSRFGenerateOptions): string;
  function verify(token: string, options?: CSRFVerifyOptions): boolean;
}