---
title: Cross Site Request Forgery (CSRF)
description: Protect user actions from unwanted state change.
links:
  - label: Optional
    icon: i-heroicons-exclamation-circle
    color: yellow
    size: xs
---

Cross-Site Request Forgery (CSRF) is an attack that forces an end user to execute unwanted actions on a web application in which they’re currently authenticated. With a little help of social engineering (such as sending a link via email or chat), an attacker may trick the users of a web application into executing actions of the attacker’s choosing. If the victim is a normal user, a successful CSRF attack can force the user to perform state changing requests like transferring funds, changing their email address, and so forth. If the victim is an administrative account, CSRF can compromise the entire web application.

::callout{icon="i-heroicons-light-bulb"}
 Read more about CRSF [here](https://owasp.org/www-community/attacks/csrf).
::

This functionality is based on the great module by [Morgan](https://github.com/Morgbn). You can check out the full documentation and reference [here](https://github.com/morgbn/nuxt-csurf)

`nuxt-csurf` is disabled by default but you can enable it with default configuration like following:

```js{}[nuxt.config.ts]
export default defineNuxtConfig({
  security: {
    csrf: true
  }
})
```
You can directly define per route settings using the `csurf` config (which is the underlying package used for CSRF protection in this library. This should be used directly, not in a `security` object)

```ts{}[nuxt.config.ts]
export default {
  routeRules: {
    '/api/nocsrf': {
      csurf: false
    }
  }
}
```
Now, you can use the auto-imported composables for handling CRSF:

```ts
// Wrapper around `useFetch` that automatically adds CSRF token in headers
const { data, pending, error, refresh } = useCsrfFetch('/api/login', { query: 'value1' })

// Have access to the CSRF token value
const { csrf } = useCsrf()
```

Apart from just enabling it, you can pass a custom configuration to the underlying `nuxt-csurf` module by using the following interface:

```ts
interface ModuleOptions {
  https?: boolean,
  cookie?: CookieSerializeOptions,
  cookieKey?: string,
  methodsToProtect?: Array<string>, // the request methods we want CSRF protection for
  excludedUrls?: Array<string|[string, string]>, // any URLs we want to exclude from CSRF protection
  encryptSecret?: string,
  encryptAlgorithm?: string
}

interface CookieSerializeOptions {
  domain?: string | undefined;
  encode?(value: string): string;
  expires?: Date | undefined;
  httpOnly?: boolean | undefined;
  maxAge?: number | undefined;
  path?: string | undefined;
  sameSite?: true | false | 'lax' | 'strict' | 'none' | undefined;
  secure?: boolean | undefined;
}
```

## Using with tRPC Nuxt

TRPC [uses `POST` requests](https://trpc.io/docs/rpc#methods---type-mapping) for the mutation endpoints. Using the CSRF protection functionality of this module with [trpc-nuxt](https://github.com/wobsoriano/trpc-nuxt) will help you protect your mutation endpoints from CSRF.

In order to make the [CSRF](/security/csrf) functionality of this module work with `trpc-nuxt`, we have to add the CSRF token value into a `csrf-token` header inside the outgoing request headers in our `trpc` client.

```ts
import { createTRPCNuxtClient, httpBatchLink } from "trpc-nuxt/client";
import type { AppRouter } from "@/server/trpc/routers";

export default defineNuxtPlugin(() => {
  const headers = useRequestHeaders();
  const { csrf } = useCsrf();

  const client = createTRPCNuxtClient<AppRouter>({
    links: [
      httpBatchLink({
        // Headers are called on every request
        headers() {
          // Add CSRF token to request headers
          return { ...headers, "csrf-token": csrf };
        },
      }),
    ],
  });

  return {
    provide: {
      client,
    },
  };
});
```