CSRF Protection

Bun provides a built-in API for generating and verifying CSRF (Cross-Site Request Forgery) tokens through Bun.CSRF. Tokens are signed with HMAC and include expiration timestamps to limit the token validity window.

csrf.ts

// Generate a token
const token = Bun.CSRF.generate("my-secret");

// Verify it
const isValid = Bun.CSRF.verify(token, { secret: "my-secret" });
console.log(isValid); // true

`Bun.CSRF.generate()`

Generate a CSRF token. The token contains a cryptographic nonce, a timestamp, and an HMAC signature, encoded as a string.

generate.ts

const token = Bun.CSRF.generate("my-secret-key");

Parameters:

secret (string, optional) — The secret key used to sign the token. If not provided, Bun generates a random in-memory default secret (unique per thread).
options (object, optional):

Option	Type	Default	Description
`expiresIn`	`number`	`86400000`	Milliseconds until the token expires. Defaults to 24 hours.
`encoding`	`string`	`"base64url"`	Token encoding format: `"base64"`, `"base64url"`, or `"hex"`.
`algorithm`	`string`	`"sha256"`	HMAC algorithm: `"sha256"`, `"sha384"`, `"sha512"`, `"sha512-256"`, `"blake2b256"`, or `"blake2b512"`.

Returns: string — the encoded token.

generate-options.ts

// Token that expires in 1 hour, encoded as hex
const token = Bun.CSRF.generate("my-secret", {
  expiresIn: 60 * 60 * 1000,
  encoding: "hex",
});

// Using a different algorithm
const token2 = Bun.CSRF.generate("my-secret", {
  algorithm: "sha512",
});

`Bun.CSRF.verify()`

Verify a CSRF token. Returns true if the token is valid and has not expired, false otherwise.

verify.ts

const isValid = Bun.CSRF.verify(token, { secret: "my-secret-key" });

Parameters:

token (string, required) — The token to verify.
options (object, optional):

Option	Type	Default	Description
`secret`	`string`	(auto)	The secret used to sign the token. If not provided, uses the same in-memory default as `generate()`.
`maxAge`	`number`	`86400000`	Maximum token age in milliseconds, independent of the token's own `expiresIn`.
`encoding`	`string`	`"base64url"`	Must match the encoding used during `generate()`.
`algorithm`	`string`	`"sha256"`	Must match the algorithm used during `generate()`.

Returns: boolean

verify-options.ts

// Verify a hex-encoded token
const isValid = Bun.CSRF.verify(hexToken, {
  secret: "my-secret",
  encoding: "hex",
});

// Enforce a shorter max age than what the token was generated with
const isValid2 = Bun.CSRF.verify(token, {
  secret: "my-secret",
  maxAge: 60 * 1000, // reject tokens older than 1 minute
});

Using with `Bun.serve()`

A typical pattern is to generate a token when rendering a form, embed it in a hidden field, and verify it when the form is submitted.

server.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">Send</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("Invalid CSRF token", { status: 403 });
        }

        return new Response("OK");
      },
    },
  },
});

console.log(`Listening on ${server.url}`);

Default secret

If you omit the secret parameter in both generate() and verify(), Bun uses a random secret generated once per thread. This is convenient for single-thread applications but won't work across multiple servers, workers, or after a restart.

default-secret.ts

// Both calls use the same per-thread default secret within this runtime context.
const token = Bun.CSRF.generate();
const isValid = Bun.CSRF.verify(token); // true

For production use, always provide an explicit secret shared across your infrastructure.

TypeScript

types.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;
}

Bun.CSRF.generate()

Bun.CSRF.verify()

Using with Bun.serve()

Default secret

TypeScript

On this page

`Bun.CSRF.generate()`

`Bun.CSRF.verify()`

Using with `Bun.serve()`