Laravel Fetch Metadata

Overview

revolution/laravel-fetch-metadata is a security middleware package that validates the Sec-Fetch-* HTTP headers sent by browsers. You can control which requests to allow based on the origin, mode, destination, and whether the request was user-initiated. By leveraging browser-built-in security features, you can block malicious requests from unauthorized origins without harming the experience for legitimate users.

In Laravel 13, CSRF protection uses the Sec-Fetch-Site header for origin validation. See CSRF protection for details.

For the full Fetch Metadata specification, see the MDN documentation.

Installation

composer require revolution/laravel-fetch-metadata

Registering middleware aliases

use Illuminate\Foundation\Configuration\Middleware;
use Revolution\FetchMetadata\Middleware\SecFetchSite;
use Revolution\FetchMetadata\Middleware\SecFetchMode;
use Revolution\FetchMetadata\Middleware\SecFetchDest;
use Revolution\FetchMetadata\Middleware\SecFetchUser;

->withMiddleware(function (Middleware $middleware) {
    $middleware->alias([
        'sec-fetch-site' => SecFetchSite::class,
        'sec-fetch-mode' => SecFetchMode::class,
        'sec-fetch-dest' => SecFetchDest::class,
        'sec-fetch-user' => SecFetchUser::class,
    ]);
})

You can also use just some of the middleware. The alias names can be anything you like.

Middleware overview

SecFetchSite

The Sec-Fetch-Site header describes the relationship between the request’s origin and the target origin. By default, only same-origin and none (direct access) are allowed.

Value	Description
`same-origin`	Same-origin request
`same-site`	Request from the same site, such as a subdomain
`cross-site`	Request from a different site
`none`	Navigation-initiated request such as the user typing a URL directly

See the MDN documentation for details.

SecFetchMode

The Sec-Fetch-Mode header describes the request mode. By default, navigate and cors are allowed.

Value	Description
`navigate`	A navigation request such as clicking a link or submitting a form
`cors`	CORS request
`no-cors`	No-cors request
`same-origin`	Same-origin request
`websocket`	WebSocket connection request

See the MDN documentation for details.

SecFetchDest

The Sec-Fetch-Dest header describes the destination resource type of the request. See the MDN documentation for details.

SecFetchUser

The Sec-Fetch-User header indicates whether the request was initiated by user interaction. The only value is ?1 (user interaction).

Using the SecFetchUser middleware will also block search engine crawlers and AI agents. Do not use it on public pages that need to be indexed.

Routing examples

Basic usage

use Illuminate\Support\Facades\Route;
use Illuminate\Http\Request;

Route::post('user/update-password', function (Request $request) {
    //
})->middleware('sec-fetch-site');

Specifying allowed values via parameters

Route::post('user/update-password', function (Request $request) {
    //
})->middleware('sec-fetch-site:cross-site');

Specifying multiple parameters

Route::post('user/update-password', function (Request $request) {
    //
})->middleware('sec-fetch-site:same-origin,cross-site');

Without an alias

use Revolution\FetchMetadata\Middleware\SecFetchSite;

Route::post('user/update-password', function (Request $request) {
    //
})->middleware(SecFetchSite::class.':same-origin,cross-site');

Combining multiple middleware

Route::post('user/update-profile', function (Request $request) {
    //
})->middleware(['sec-fetch-site:same-origin', 'sec-fetch-mode:navigate']);

Error handling

When a Sec-Fetch-* header value is invalid, Symfony\Component\HttpKernel\Exception\BadRequestHttpException is thrown. You can customize the response in bootstrap/app.php.

use Illuminate\Http\Request;
use Symfony\Component\HttpKernel\Exception\BadRequestHttpException;

->withExceptions(function (Exceptions $exceptions) {
    $exceptions->render(function (BadRequestHttpException $e, Request $request) {
        if ($request->expectsJson()) {
            return response()->json([
                'message' => $e->getMessage(),
            ], 400);
        }
    });
})

Relationship with CSRF protection

In Laravel 13, the PreventRequestForgery middleware now uses the Sec-Fetch-Site header for origin validation as the first step in CSRF protection. This package lets you apply Fetch Metadata headers at a finer grain to further harden your application. See CSRF protection for details.

For the latest updates, see the GitHub repository.

GitHub Copilot

SDK

AI SDK

VOICEVOX

Starter Kits

Feeds and RSS

Middleware

Overview

Installation

Registering middleware aliases

Middleware overview

SecFetchSite

SecFetchMode

SecFetchDest

SecFetchUser

Routing examples

Basic usage

Specifying allowed values via parameters

Specifying multiple parameters

Without an alias

Combining multiple middleware

Error handling

Relationship with CSRF protection

​Overview

​Installation

​Registering middleware aliases

​Middleware overview

​SecFetchSite

​SecFetchMode

​SecFetchDest

​SecFetchUser

​Routing examples

​Basic usage

​Specifying allowed values via parameters

​Specifying multiple parameters

​Without an alias

​Combining multiple middleware

​Error handling

​Relationship with CSRF protection

Overview

Installation

Registering middleware aliases

Middleware overview

SecFetchSite

SecFetchMode

SecFetchDest

SecFetchUser

Routing examples

Basic usage

Specifying allowed values via parameters

Specifying multiple parameters

Without an alias

Combining multiple middleware

Error handling

Relationship with CSRF protection