In this tutorial, we will learn how to implement CSRF (Cross-Site Request Forgery) protection in Lithe to prevent unwanted requests from being made to your application. This guide is designed for beginners, so we'll go step by step!

What is CSRF?

CSRF, or Cross-Site Request Forgery, is a type of attack where a user is tricked into executing an unauthorized action on a website where they are authenticated. This attack is dangerous because the attacker can manipulate data or access restricted areas. To prevent this, we add a security layer that stops suspicious requests from being processed.

Tutorial Structure

1. Set Up Lithe
2. Install CSRF Middleware
3. Add CSRF Token on the Backend
4. Verify the Token on the Backend
5. Send the Token from the Frontend
6. Test CSRF Protection

Let’s get started!

Step 1: Setting Up Lithe

If you haven't set up Lithe yet, start by installing the framework with the command below:

composer create-project lithephp/lithephp project-name
cd project-name

This creates a basic structure for your project with Lithe.

Step 2: Installing CSRF Middleware

The CSRF middleware helps generate and validate CSRF tokens. To install it, run the following command in the terminal within your project:

composer require lithemod/csrf

Step 3: Configuring CSRF Middleware

Now, we need to tell Lithe that we want to use the CSRF middleware. Open the main file src/App.php and add the CSRF middleware.

use Lithe\Middleware\Security\csrf;
use function Lithe\Orbis\Http\Router\router;

$app = new \Lithe\App;

// Configure the CSRF middleware with automatic checking in the request body
$app->use(csrf([
    'expire' => 600, // Token expiration after 10 minutes
    'checkBody' => true, // Enables automatic checking in the body
    'bodyMethods' => ['POST', 'PUT', 'DELETE'], // Defines the methods for checking CSRF in the body
]));

$app->use(router(__DIR__ . '/routes/web'));

$app->listen();

With this, the CSRF middleware is active in our application, and every request that requires protection must include a valid token.

Step 4: Generating the CSRF Token

To use CSRF protection, we need to generate a unique token and include it in the requests. We’ll create a route to send a form that automatically includes the CSRF token.

1. Create a file named src/routes/web.php, and add the form route with a field for the CSRF token.

use Lithe\Http\{Request, Response};
use function Lithe\Orbis\Http\Router\get;

get('/form', function (Request $req, Response $res) {
    // Generate the CSRF token field
    $tokenField = $req->csrf->getTokenField();

    // Send the HTML with the token included in the form
    return $res->send("
        <form method='POST' action='/submit'>
            $tokenField
            <input type='text' name='data' placeholder='Type something' required>
            <button type='submit'>Submit</button>
        </form>
    ");
});

1. This route creates a form that includes the CSRF token field. The field is mandatory for Lithe to check the authenticity of the request.

Step 5: Verifying the Token on the Backend

When the form is submitted, Lithe will automatically check if the token is valid. Now, let’s create the route that will receive and process the form.

1. In the same file src/routes/web.php, add the route to process the form submission.

use function Lithe\Orbis\Http\Router\post;

post('/submit', function (Request $req, Response $res) {
    // Lithe automatically checks the token, so we just need to process the data
    $data = $req->input('data');
    return $res->json([
        'message' => 'Data received successfully!',
        'data' => $data,
    ]);
});

If the token is invalid or missing, Lithe will automatically block the request and return an error.

Step 6: Sending Requests with the CSRF Token

On the frontend, whenever you need to send a POST request (or another data-altering method), it's important to include the CSRF token in the body of the request or in the header, depending on how you configured your middleware.

Example with JavaScript Fetch API

For those using JavaScript, here’s an example of how to send the token with a fetch request:

fetch('/submit', {
    method: 'POST',
    headers: {
        'Content-Type': 'application/x-www-form-urlencoded'
    },
    body: '_token=' + document.querySelector('input[name="_token"]').value + '&data=example'
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error('Error:', error));

Step 7: Testing CSRF Protection

1. Access the /form route in your browser. You will see the form with the CSRF token included.
2. Fill in the field and submit the form.
3. If everything is working, you will see a success message with the data sent.

Summary and Final Considerations

In this tutorial, we learned:

• What CSRF is and why it’s important.
• How to set up a CSRF middleware in Lithe.
• How to generate and verify CSRF tokens on the backend.
• How to send CSRF tokens with forms and AJAX requests.

With this protection implemented, you make your application more secure against CSRF attacks, helping to protect the integrity of your users' data.

For more detailed information, check out the official Lithe Documentation.