> ## Documentation Index
> Fetch the complete documentation index at: https://kawax.biz/llms.txt
> Use this file to discover all available pages before exploring further.

# Laravel Fetch Metadata

> Middleware di sicurezza che sfrutta le header Sec-Fetch-* per proteggere le app Laravel da attacchi CSRF e richieste cross-site.

## Panoramica

[revolution/laravel-fetch-metadata](https://github.com/invokable/laravel-fetch-metadata) è un pacchetto middleware di sicurezza che verifica le header HTTP `Sec-Fetch-*` inviate dal browser. Puoi controllare quali richieste ammettere in base a origine, modalità, destinazione e presenza di interazione utente.

Sfruttando le funzionalità di sicurezza integrate nel browser puoi bloccare richieste malevole da origini non autorizzate senza compromettere l'esperienza degli utenti legittimi.

<Info>
  In Laravel 13 la verifica dell'Origin nella protezione CSRF utilizza la header `Sec-Fetch-Site`. Per i dettagli consulta [Protezione CSRF](/it/csrf).
</Info>

Per le specifiche dettagliate di Fetch Metadata consulta la [documentazione MDN](https://developer.mozilla.org/ja/docs/Glossary/Fetch_metadata_request_header).

## Installazione

```bash theme={null}
composer require revolution/laravel-fetch-metadata
```

### Registrazione degli alias di middleware

Registra gli alias dei middleware in `bootstrap/app.php`.

```php theme={null}
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,
    ]);
})
```

Puoi usare anche solo alcuni middleware. Puoi rinominare gli alias a piacere.

## Descrizione dei middleware

### SecFetchSite

La header `Sec-Fetch-Site` indica la relazione tra l'origine della richiesta e quella del target. Per impostazione predefinita ammette solo `same-origin` e `none` (accesso diretto).

| Valore        | Descrizione                                                                      |
| ------------- | -------------------------------------------------------------------------------- |
| `same-origin` | Richiesta dalla stessa origine                                                   |
| `same-site`   | Richiesta dallo stesso sito (es. da sottodomini)                                 |
| `cross-site`  | Richiesta da un sito diverso                                                     |
| `none`        | Richieste che nascono dalla navigazione, ad esempio quando l'utente digita l'URL |

Per i dettagli consulta la [documentazione MDN](https://developer.mozilla.org/ja/docs/Web/HTTP/Headers/Sec-Fetch-Site).

### SecFetchMode

La header `Sec-Fetch-Mode` indica la modalità della richiesta. Per impostazione predefinita ammette `navigate` e `cors`.

| Valore        | Descrizione                                                 |
| ------------- | ----------------------------------------------------------- |
| `navigate`    | Richieste di navigazione, es. click su link o invio di form |
| `cors`        | Richiesta CORS                                              |
| `no-cors`     | Richiesta no-cors                                           |
| `same-origin` | Richiesta same-origin                                       |
| `websocket`   | Richiesta di connessione WebSocket                          |

Per i dettagli consulta la [documentazione MDN](https://developer.mozilla.org/ja/docs/Web/HTTP/Headers/Sec-Fetch-Mode).

### SecFetchDest

La header `Sec-Fetch-Dest` indica il tipo di risorsa destinazione della richiesta.

Per i dettagli consulta la [documentazione MDN](https://developer.mozilla.org/ja/docs/Web/HTTP/Headers/Sec-Fetch-Dest).

### SecFetchUser

La header `Sec-Fetch-User` indica se la richiesta è stata avviata da un'azione dell'utente. Il valore è solo `?1` (interazione utente presente).

<Warning>
  Se usi il middleware `SecFetchUser` blocchi anche i crawler dei motori di ricerca e gli agenti AI. Non usarlo su pagine pubbliche che devono essere indicizzate.
</Warning>

## Esempi di utilizzo nelle rotte

### Uso base

```php theme={null}
use Illuminate\Support\Facades\Route;
use Illuminate\Http\Request;

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

### Specifica dei valori consentiti tramite parametro

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

### Specifica di più parametri

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

### Senza usare gli alias

```php theme={null}
use Revolution\FetchMetadata\Middleware\SecFetchSite;

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

### Combinare più middleware

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

## Gestione degli errori

Se il valore di una header `Sec-Fetch-*` non è valido, viene lanciata `Symfony\Component\HttpKernel\Exception\BadRequestHttpException`.

Puoi personalizzare la risposta in `bootstrap/app.php`.

```php theme={null}
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);
        }
    });
})
```

## Relazione con la protezione CSRF

In Laravel 13 il middleware `PreventRequestForgery` esegue la verifica dell'Origin tramite la header `Sec-Fetch-Site` come primo passo della protezione CSRF. Questo pacchetto sfrutta le header Fetch Metadata a una granularità ancora maggiore, rafforzando la sicurezza dell'applicazione.

Per i dettagli consulta [Protezione CSRF](/it/csrf).

<Info>
  Per le informazioni più aggiornate consulta la [repository su GitHub](https://github.com/invokable/laravel-fetch-metadata).
</Info>


## Related topics

- [Laravel MCP](/it/mcp.md)
- [Guida all'aggiornamento da Laravel 12 a 13](/it/blog/upgrade-12-to-13.md)
- [Socialite - Laravel Bluesky](/it/packages/laravel-bluesky/socialite.md)
- [Contesto e filtraggio della sessione](/it/packages/laravel-copilot-sdk/session-context.md)
- [Eventi del ciclo di vita della sessione](/it/packages/laravel-copilot-sdk/session-lifecycle-event.md)